1#!/usr/bin/env python3 2# SPDX-License-Identifier: GPL-2.0 3""" 4Unit‑test driver for kernel‑doc YAML tests. 5 6Two kinds of tests are defined: 7 8* **Schema‑validation tests** – if ``jsonschema`` is available, the 9 YAML files in this directory are validated against the JSON‑Schema 10 described in ``kdoc-test-schema.yaml``. When the library is not 11 present, a warning is emitted and the validation step is simply 12 skipped – the dynamic kernel‑doc tests still run. 13 14* **Kernel‑doc tests** – dynamically generate one test method per 15 scenario in ``kdoc-test.yaml``. Each method simply forwards 16 the data to ``self.run_test`` – you only need to implement that 17 helper in your own code. 18 19File names are kept as module‑level constants so that the 20implementation stays completely independent of ``pathlib``. 21""" 22 23import os 24import sys 25import warnings 26import yaml 27import unittest 28from typing import Any, Dict, List 29 30SRC_DIR = os.path.dirname(os.path.realpath(__file__)) 31sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python")) 32 33from unittest_helper import run_unittest 34 35 36# 37# Files to read 38# 39BASE = os.path.realpath(os.path.dirname(__file__)) 40 41SCHEMA_FILE = os.path.join(BASE, "kdoc-test-schema.yaml") 42TEST_FILE = os.path.join(BASE, "kdoc-test.yaml") 43 44# 45# Schema‑validation test 46# 47class TestYAMLSchemaValidation(unittest.TestCase): 48 """ 49 Checks if TEST_FILE matches SCHEMA_FILE. 50 """ 51 52 @classmethod 53 def setUpClass(cls): 54 """ 55 Import jsonschema if available. 56 """ 57 58 try: 59 from jsonschema import Draft7Validator 60 except ImportError: 61 print("Warning: jsonschema package not available. Skipping schema validation") 62 cls.validator = None 63 return 64 65 with open(SCHEMA_FILE, encoding="utf-8") as fp: 66 cls.schema = yaml.safe_load(fp) 67 68 cls.validator = Draft7Validator(cls.schema) 69 70 def test_kdoc_test_yaml_followsschema(self): 71 """ 72 Run jsonschema validation if the validator is available. 73 If not, emit a warning and return without failing. 74 """ 75 if self.validator is None: 76 return 77 78 with open(TEST_FILE, encoding="utf-8") as fp: 79 data = yaml.safe_load(fp) 80 81 errors = self.validator.iter_errors(data) 82 83 msgs = [] 84 for error in errors: 85 msgs.append(error.message) 86 87 if msgs: 88 self.fail("Schema validation failed:\n\t" + "\n\t".join(msgs)) 89 90# -------------------------------------------------------------------- 91# Entry point 92# -------------------------------------------------------------------- 93if __name__ == "__main__": 94 run_unittest(__file__) 95