Repository: cocotb/cocotb

Issue:
Getting rid of None in an option of TestFactory
Hello everyone,

I did not find this in the documentation, so maybe you can push me in the right direction:
I want to use TestFactory to supply a list of discrete values to create different tests. To achieve this, I create a function annotated with @cocotb.test **run_test(dut, my_option=None)** which has the general structure of my test, depending on the value of my_option.
After defining this function, I do the following:
```
factory = TestFactory(run_test)
factory.add_option("my_option", list_of_values)
factory.generate_tests()
```
And it almost works as expected. It creates a test for each of my entries. However, the first test that gets created provides the value None to the parameter my_option. Therefore, I have one more test than intended which obviously fails, as I cannot do anything sensible with None in my test. I assume that this is the result of cocotb running all functions annotated with @cocotb.test if I don't supply the TESTCASE environment variable. Using cocotb.coroutine as an annotation resolves my problem, but I highly appreciate the timeout functionality of the cocotb.test annotation. Is there a clean way how to ensure that the default implementation of my function is not used as a test, without the need to hardcode the test names in TESTCASE?

Cheers and thanks in advance!



Discussion:
Don't decorate `run_test` with `cocotb.test`, instead use `cocotb.coroutine`.
Hello @ktbarrett ,
as I mentioned, doing that resolves my problem, but I lose the timeout functionality of cocotb.test, or is there another fast way to achieve timeouts in the test function? Anyways, thanks for your quick reply!
You could use https://docs.cocotb.org/en/latest/triggers.html#cocotb.triggers.with_timeout
Thanks!
@ktbarrett, could you update the docs for `cocotb.test` to point to `triggers.with_timeout` for an explanation of the timeout arguments?

Resolving patch:
diff --git a/cocotb/decorators.py b/cocotb/decorators.py
--- a/cocotb/decorators.py
+++ b/cocotb/decorators.py
@@ -413,12 +413,17 @@ class test(coroutine, metaclass=_decorator_helper):
     Used as ``@cocotb.test(...)``.
 
     Args:
-        timeout_time (int, optional):
-            Value representing simulation timeout.
+        timeout_time (numbers.Real or decimal.Decimal, optional):
+            Simulation time duration before timeout occurs.
 
             .. versionadded:: 1.3
-        timeout_unit (str, optional):
-            Unit of timeout value, see :class:`~cocotb.triggers.Timer` for more info.
+
+            .. note::
+                Test timeout is intended for protection against deadlock.
+                Users should use :class:`~cocotb.triggers.with_timeout` if they require a
+                more general-purpose timeout mechanism.
+        timeout_unit (str or None, optional):
+            Units of timeout_time, accepts any units that :class:`~cocotb.triggers.Timer` does.
 
             .. versionadded:: 1.3
         expect_fail (bool, optional):
diff --git a/cocotb/triggers.py b/cocotb/triggers.py
--- a/cocotb/triggers.py
+++ b/cocotb/triggers.py
@@ -805,12 +805,12 @@ async def with_timeout(trigger, timeout_time, timeout_unit=None):
         await with_timeout(First(coro, event.wait()), 100, 'ns')
 
     Args:
-        trigger (cocotb_waitable):
+        trigger (:class:`~cocotb.triggers.Trigger` or :class:`~cocotb.triggers.Waitable` or :class:`~cocotb.decorators.RunningTask`):
             A single object that could be right of an :keyword:`await` expression in cocotb.
         timeout_time (numbers.Real or decimal.Decimal):
-            Time duration.
+            Simulation time duration before timeout occurs.
         timeout_unit (str or None, optional):
-            Units of duration, accepts any values that :class:`~cocotb.triggers.Timer` does.
+            Units of timeout_time, accepts any units that :class:`~cocotb.triggers.Timer` does.
 
     Returns:
         First trigger that completed if timeout did not occur.


Test patch: