[feat] Introduce new syntax for allowing the creation of extensible parametrised tests

.gitignore

@@ -96,3 +96,6 @@ ENV/
 
 # TextMATE files
 ._*
+
+# Vim temp files
+*.swp

docs/regression_test_api.rst

@@ -36,6 +36,59 @@ Pipeline Hooks
 .. autodecorator:: reframe.core.decorators.require_deps
 
 
+.. _directives:
+
+Directives
+----------
+
+Directives are functions that can be called directly in the body of a ReFrame regression test class. 
+These functions exert control over the test creation, and they allow adding and/or modifying certain attributes of the regression test.
+For example, a test can be parameterized using the :func:`parameter` directive as follows:
+
+.. code:: python
+
+    class MyTest(rfm.RegressionTest):
+        parameter('variant', 'A', 'B')
+
+        def __init__(self):
+            if self.variant == 'A':
+                do_this()
+            else:
+                do_other()
+
+One of the most powerful features about using directives is that they store their input information at the class level. 
+This means if one were to extend or specialize an existing regression test, the test attribute additions and modifications made through directives in the parent class will be automatically inherited by the child test.
+For instance, continuing with the example above, one could override the :func:`__init__` method in the :class:`MyTest` regression test as follows:
+
+.. code:: python
+
+    class MyModifiedTest(MyTest):
+
+        def __init__(self):
+            if self.variant == 'A':
+                override_this()
+            else:
+                override_other()
+
+
+.. py:function:: reframe.core.pipeline.RegressionTest.parameter(name, *values, inherit_params=False, filter_params=None)
+
+   Inserts or modifies a regression test parameter.
+   If a parameter with a matching name is already present in the parameter space of a parent class, the existing parameter values will be combined with those provided by this method following the inheritance behaviour set by the arguments ``inherit_params`` and ``filter_params``.
+   Instead, if no parameter with a matching name exists in any of the parent parameter spaces, a new regression test parameter is created.
+
+   :param name: the parameter name.
+   :param values: the parameter values.
+       If no values are passed when creating a new parameter, the parameter is considered as *declared* but not *defined* (i.e. an abstract parameter).
+       Instead, for an existing parameter, this depends on the parameter's inheritance behaviour and on whether any values where provided in any of the parent parameter spaces.
+   :param inherit_params: If :obj:`False`, no parameter values that may have been defined in any of the parent parameter spaces will be inherited.
+   :param filter_params: Function to filter/modify the inherited parameter values that may have been provided in any of the parent parameter spaces.
+       This function must accept a single argument, which will be passed as an iterable containing the inherited parameter values.
+       This only has an effect if used with ``inherit_params=True``.
+
+
+
+
 Environments and Systems
 ------------------------
 

reframe/core/decorators.py

@@ -27,13 +27,20 @@
 
 
 def _register_test(cls, args=None):
+    '''Register the test.
+
+    Register the test with _rfm_use_params=True. This additional argument flags
+    this case to consume the parameter space. Otherwise, the regression test
+    parameters would simply be initialized to None.
+    '''
     def _instantiate(cls, args):
         if isinstance(args, collections.abc.Sequence):
-            return cls(*args)
+            return cls(*args, _rfm_use_params=True)
         elif isinstance(args, collections.abc.Mapping):
+            args['_rfm_use_params'] = True
             return cls(**args)
         elif args is None:
-            return cls()
+            return cls(_rfm_use_params=True)
 
     def _instantiate_all():
         ret = []
@@ -72,19 +79,25 @@ def _validate_test(cls):
         raise ReframeSyntaxError('the decorated class must be a '
                                  'subclass of RegressionTest')
 
+    if (cls.is_abstract()):
+        raise ValueError(f'decorated test ({cls.__qualname__!r}) is an'
+                         f' abstract test')
+
 
 def simple_test(cls):
-    '''Class decorator for registering parameterless tests with ReFrame.
+    '''Class decorator for registering tests with ReFrame.
 
     The decorated class must derive from
     :class:`reframe.core.pipeline.RegressionTest`.  This decorator is also
     available directly under the :mod:`reframe` module.
 
     .. versionadded:: 2.13
     '''
-
     _validate_test(cls)
-    _register_test(cls)
+
+    for _ in cls.param_space:
+        _register_test(cls)
+
     return cls
 
 
@@ -106,6 +119,11 @@ def parameterized_test(*inst):
     '''
     def _do_register(cls):
         _validate_test(cls)
+        if not cls.param_space.is_empty():
+            raise ValueError(
+                f'{cls.__qualname__!r} is already a parameterized test'
+            )
+
         for args in inst:
             _register_test(cls, args)
 

reframe/core/meta.py

@@ -7,13 +7,32 @@
 # Meta-class for creating regression tests.
 #
 
+
 from reframe.core.exceptions import ReframeSyntaxError
+import reframe.core.parameters as parameters
 
 
 class RegressionTestMeta(type):
+    @classmethod
+    def __prepare__(cls, name, bases, **kwargs):
+        namespace = super().__prepare__(name, bases, **kwargs)
+
+        # Regression test parameter space defined at the class level
+        local_param_space = parameters.LocalParamSpace()
+        namespace['_rfm_local_param_space'] = local_param_space
+
+        # Directive to add a regression test parameter directly in the
+        # class body as: `parameter('P0', 0,1,2,3)`.
+        namespace['parameter'] = local_param_space.add_param
+
+        return namespace
+
     def __init__(cls, name, bases, namespace, **kwargs):
         super().__init__(name, bases, namespace, **kwargs)
 
+        # Build the regression test parameter space
+        cls._rfm_param_space = parameters.ParamSpace(cls)
+
         # Set up the hooks for the pipeline stages based on the _rfm_attach
         # attribute; all dependencies will be resolved first in the post-setup
         # phase if not assigned elsewhere
@@ -59,3 +78,42 @@ def __init__(cls, name, bases, namespace, **kwargs):
                            f"'{b.__qualname__}.{v.__name__}'; "
                            f"you should use the pipeline hooks instead")
                     raise ReframeSyntaxError(msg)
+
+    def __call__(cls, *args, **kwargs):
+        '''Intercept reframe-specific constructor arguments.
+
+        When registering a regression test using any supported decorator,
+        this decorator may pass additional arguments to the class constructor
+        to perform specific reframe-internal actions. This gives extra control
+        over the class instantiation process, allowing reframe to instantiate
+        the regression test class differently if this class was registered or
+        not (e.g. when deep-copying a regression test object). These interal
+        arguments must be intercepted before the object initialization, since
+        these would otherwise affect the __init__ method's signature, and these
+        internal mechanisms must be fully transparent to the user.
+        '''
+        obj = cls.__new__(cls, *args, **kwargs)
+
+        # Intercept constructor arguments
+        kwargs.pop('_rfm_use_params', None)
+
+        obj.__init__(*args, **kwargs)
+        return obj
+
+    @property
+    def param_space(cls):
+        # Make the parameter space available as read-only
+        return cls._rfm_param_space
+
+    def is_abstract(cls):
+        '''Check if the test is an abstract test.
+
+        If the parameter space has undefined parameters, the test is considered
+        an abstract test. If that is the case, the length of the parameter
+        space is just 0.
+
+        :return: bool indicating wheteher the test is abstract or not
+
+        :meta private:
+        '''
+        return len(cls.param_space) == 0