diff --git a/scripts/mbedtls_dev/test_generation.py b/scripts/mbedtls_dev/test_generation.py index 4803c24b6..9e004a69f 100644 --- a/scripts/mbedtls_dev/test_generation.py +++ b/scripts/mbedtls_dev/test_generation.py @@ -35,6 +35,8 @@ T = TypeVar('T') #pylint: disable=invalid-name class BaseTarget(metaclass=ABCMeta): """Base target for test case generation. + This should be derived from for file Targets. + Attributes: count: Counter for test cases from this class. case_description: Short description of the test case. This may be @@ -43,7 +45,8 @@ class BaseTarget(metaclass=ABCMeta): should be specified in a child class of BaseTarget. test_function: Test function which the class generates cases for. test_name: A common name or description of the test function. This can - be the function's name, or a short summary of its purpose. + be `test_function`, a clearer equivalent, or a short summary of the + test function's purpose. """ count = 0 case_description = "" @@ -61,7 +64,7 @@ class BaseTarget(metaclass=ABCMeta): """Get the list of arguments for the test case. Override this method to provide the list of arguments required for - generating the test_function. + the `test_function`. Returns: List of arguments required for the test function. @@ -69,12 +72,12 @@ class BaseTarget(metaclass=ABCMeta): raise NotImplementedError def description(self) -> str: - """Create a test description. + """Create a test case description. Creates a description of the test case, including a name for the test - function, and describing the specific test case. This should inform a - reader of the purpose of the case. The case description may be - generated in the class, or provided manually as needed. + function, a case number, and a description the specific test case. + This should inform a reader what is being tested, and provide context + for the test case. Returns: Description for the test case. @@ -85,7 +88,7 @@ class BaseTarget(metaclass=ABCMeta): def create_test_case(self) -> test_case.TestCase: - """Generate TestCase from the current object.""" + """Generate TestCase from the instance.""" tc = test_case.TestCase() tc.set_description(self.description()) tc.set_function(self.test_function) @@ -96,7 +99,7 @@ class BaseTarget(metaclass=ABCMeta): @classmethod @abstractmethod def generate_function_tests(cls) -> Iterator[test_case.TestCase]: - """Generate test cases for the test function. + """Generate test cases for the class test function. This will be called in classes where `test_function` is set. Implementations should yield TestCase objects, by creating instances @@ -111,11 +114,10 @@ class BaseTarget(metaclass=ABCMeta): In classes with `test_function` set, `generate_function_tests()` is used to generate test cases first. - In all classes, this method will iterate over its subclasses, and - yield from `generate_tests()` in each. - Calling this method on a class X will yield test cases from all classes - derived from X. + In all classes, this method will iterate over its subclasses, and + yield from `generate_tests()` in each. Calling this method on a class X + will yield test cases from all classes derived from X. """ if cls.test_function: yield from cls.generate_function_tests() diff --git a/tests/scripts/generate_bignum_tests.py b/tests/scripts/generate_bignum_tests.py index 2443f659b..4486d4958 100755 --- a/tests/scripts/generate_bignum_tests.py +++ b/tests/scripts/generate_bignum_tests.py @@ -6,25 +6,33 @@ generate only the specified files. Class structure: -Target classes are directly derived from test_generation.BaseTarget, -representing a target file. These indicate where test cases will be written -to in classes derived from the Target. Multiple Target classes must not -represent the same target_basename. +Child classes of test_generation.BaseTarget (file Targets) represent a target +file. These indicate where test cases will be written to, for all subclasses of +this Target. Multiple Target classes should not reuse a `target_basename`. -Each subclass derived from a Target can either be: +Each subclass derived from a file Target can either be: - A concrete class, representing a test function, which generates test cases. - An abstract class containing shared methods and attributes, not associated - with a test function. An example is BignumOperation, which provides common - features used in binary bignum operations. + with a test function. An example is BignumOperation, which provides + common features used for bignum binary operations. + +Both concrete and abstract subclasses can be derived from, to implement +additional test cases (see BignumCmp and BignumCmpAbs for examples of deriving +from abstract and concrete classes). -Adding test generation for a function: +Adding test case generation for a function: A subclass representing the test function should be added, deriving from a -Target class or a descendant. This subclass must set/implement the following: +file Target. This test class must set/implement the following: - test_function: the function name from the associated .function file. - - arguments(): generation of the arguments required for the test_function. - - generate_function_test(): generation of the test cases for the function. + - test_name: a descriptive name or brief summary to refer to the test + function. + - arguments(): a method to generate the list of arguments required for the + test_function. + - generate_function_test(): a method to generate TestCases for the function. + This should create instances of the class with required input data, and + call `.create_test_case()` to yield the TestCase. Additional details and other attributes/methods are given in the documentation of BaseTarget in test_generation.py. @@ -71,7 +79,7 @@ class BignumTarget(test_generation.BaseTarget, metaclass=ABCMeta): class BignumOperation(BignumTarget, metaclass=ABCMeta): - """Common features for test cases covering binary bignum operations. + """Common features for bignum binary operations. This adds functionality common in binary operation tests. This includes generation of case descriptions, using descriptions of values and symbols @@ -130,7 +138,7 @@ class BignumOperation(BignumTarget, metaclass=ABCMeta): """Generate a description of the argument val. This produces a simple description of the value, which are used in test - case naming, to add context to the test cases. + case naming, to add context. """ if val == "": return "0 (null)" @@ -150,7 +158,7 @@ class BignumOperation(BignumTarget, metaclass=ABCMeta): @classmethod def get_value_pairs(cls) -> Iterator[Tuple[str, str]]: - """Generator for pairs of inputs. + """Generator to yield pairs of inputs. Combinations are first generated from all input values, and then specific cases provided. @@ -169,7 +177,7 @@ class BignumOperation(BignumTarget, metaclass=ABCMeta): class BignumCmp(BignumOperation): - """Target for bignum comparison test cases.""" + """Test cases for bignum value comparison.""" count = 0 test_function = "mbedtls_mpi_cmp_mpi" test_name = "MPI compare" @@ -190,7 +198,7 @@ class BignumCmp(BignumOperation): class BignumCmpAbs(BignumCmp): - """Target for bignum comparison, absolute variant.""" + """Test cases for absolute bignum value comparison.""" count = 0 test_function = "mbedtls_mpi_cmp_abs" test_name = "MPI compare (abs)" @@ -200,7 +208,7 @@ class BignumCmpAbs(BignumCmp): class BignumAdd(BignumOperation): - """Target for bignum addition test cases.""" + """Test cases for bignum value addition.""" count = 0 test_function = "mbedtls_mpi_add_mpi" test_name = "MPI add" @@ -223,7 +231,7 @@ class BignumAdd(BignumOperation): class BignumTestGenerator(test_generation.TestGenerator): - """Test generator subclass including bignum targets.""" + """Test generator subclass setting bignum targets.""" TARGETS = { subclass.target_basename: subclass.generate_tests for subclass in test_generation.BaseTarget.__subclasses__()