Clarify documentation
Signed-off-by: Werner Lewis <werner.lewis@arm.com>
diff --git a/scripts/mbedtls_dev/test_generation.py b/scripts/mbedtls_dev/test_generation.py
index 4803c24..9e004a6 100644
--- a/scripts/mbedtls_dev/test_generation.py
+++ b/scripts/mbedtls_dev/test_generation.py
@@ -35,6 +35,8 @@
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 @@
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 @@
"""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 @@
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 @@
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 @@
@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 @@
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 2443f65..4486d49 100755
--- a/tests/scripts/generate_bignum_tests.py
+++ b/tests/scripts/generate_bignum_tests.py
@@ -6,25 +6,33 @@
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 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 @@
"""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 @@
@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 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 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 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 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__()