Decorators

Decorators can be used to change the behaviour of a method by decorating it.

Decorators that are included in htf are:

htf.test

Decorate function or method to be interpreted as a test.

@htf.test
def function():
    pass
htf.test(func)

Mark a function or method as a test.

htf.after

Run additional commands after the test function.

def run_after(*args, **kwargs):
    print("run_after", args, kwargs)

@after(run_after, 1, 2, 3, a="b")
def function():
    print("function")
function()
# prints:
# function
# run_after (1, 2, 3) {'a': 'b'}
htf.after(after_function, *after_args, **after_kwargs)

The @after decorator decorates a method so that after_function is called after the decorated function is called itself.

Parameters

  • after_function (callable) – the function to be run after the decorated function.

  • *after_args (tuple) – positional arguments to be passed to afterFunction.

  • **after_kwargs (dict) – keyword-arguments to be passed to afterFunction.

htf.before

Run additional commands before the test function.

def run_before(*args, **kwargs):
    print("runBefore", args, kwargs)

@before(run_before, 1, 2, 3, a="b")
def function():
    print("function")
function()
# prints:
# run_before (1, 2, 3) {'a': 'b'}
# function
htf.before(before_function, *before_args, **before_kwargs)

The @before decorator decorates a method so that before_function is called before the decorated function is called itself.

Parameters

  • before_function (callable) – the function to be run before the decorated function.

  • *before_args (tuple) – positional arguments to be passed to beforeFunction.

  • **before_kwargs (dict) – keyword-arguments to be passed to beforeFunction.

htf.enqueue_exception

Decorate a method to fetch its exception that is enqueued into an exception queue. The enqueued exception can be handled elsewhere. The caught exception can be raised after enqueueing it.

Just decorate you method with the queue to be used and every exception that is raised within the decorated method will be put into the queue before the exception is raised again.

@enqueueException(queue)
def decoratedMethod():
    raise Exception("This is a test")
htf.enqueue_exception(queue)

Decorate a method to fetch its exception that is enqueued into an exception queue. The enqueued exception can be handled elsewhere. The caught exception can be raised after enqueueing it.

Just decorate you method with the queue to be used and every exception that is raised within the decorated method will be put into the queue before the exception is raised again.

Parameters

queue (queue) – the queue to enqueue the exception.

htf.requirements

Used to show that a test checks a certain requirement.

@requirements("REQ_1", "REQ_2")
def test_with_requirements():
    pass
htf.requirements(*requirements)

The @requirements decorator reports which requirements are checked by a test in the test report shown in the HTMLTestReport.

Parameters

*requirements (tuple of str) – a tuple of strings that name the checked requirements, eg. “REQ_1”, “REQ_2”, etc.

htf.meets_doors_requirements

To use in conjunction with the doors_testreport to show that a test checks a certain requirement.

@meets_doors_requirements("doors://host:port/path-without-id-",
                   "REQ_1", "REQ_2")
def test_with_a_useful_name():
    pass
htf.meets_doors_requirements(base_url, *requirements)

The @meets_doors_requirements decorator reports which requirements are checked by a test in the test report shown in the doors_testreport and the HTMLTestReport.

Parameters

  • base_url (str) – the DOORS base url the links are created with.

  • *requirements (tuple of str) – a tuple of strings that name the checked requirements, eg. “REQ_1”, “REQ_2”, etc.

htf.periodic

Run a decorated function periodically.

@periodic(period=1.0)
def periodically_called_every_second():
    print("call")

@periodic can also be used within classes

class ClassWithAPeriodicMethod():

    @periodic(period=1.0)
    def periodically_called_every_second(self):
        print("call")
htf.periodic(period, maximum_period=None, run_condition_lambda=None, raise_exception=True)

Decorate a method to be run periodically.

Parameters

  • period (float) – the period in seconds.

  • maximum_period=None (float) – if set to a float >= period the periodic method may take up to maximum_period time without raising an exception. A warning is printed on stdout instead.

  • run_condition_lambda=None (callable) – a callable (method or lambda expression) that has to return true while the method is run periodically.

  • raise_exception=True (bool) – if set to True an exception is raised if the called method takes longer than the period (or maximum_period if set).

Warning

Non-realtime operating systems will not ensure timing accuracy.

htf.raises

The decorated function will catch an exception

@raises(AssertionError)
def test_failure(assertions):
    assertions.assert_true(False)

@raises(TimeoutException, UnknownException)
def test_exceptions():
    raise TimeoutException("timeout")
    raise UnknownException("unknown exception")
htf.raises(*exceptions)

Decorate a method to catch different exceptions.

Parameters

*exceptions (list of exceptions) – a tuple of exceptions that are fetched.

htf.skip

Decorate to skip the test method or function.

@skip("This test is skipped in view of the occasion")
def test_always_skipped():
    pass
htf.skip(reason)

Decorate a method to be skipped in view of the occasion.

Parameters

reason (str) – the reason to be put into the test report.

Raises

SkipTest – to skip the test.

htf.skip_if

Decorate to skip test if condition evaluates to True at runtime.

def skip_tests():
    return True

@skip_if(skip_tests, "Skipped if skip_tests returns True")
def test_skipped_if():
    pass

@skip_if(True, "Always skipped")
def test_always_skipped():
    pass

@skip_if(False, "Never skipped")
def test_never_skipped():
    pass

@skip_if(lambda: True, "Always skipped")
def test_always_skipped_lambda():
    pass

def condition():
    return True

@skip_if(condition, "skipped")
def test_always_skipped_with_bound_method(self):
    pass
htf.skip_if(condition, reason)

Decorate a method to be skipped. The condition is evaluated at runtime.

Parameters

  • condition (bool or callable) – the condition may be True, False or a callable object that must return True or False. The decorated test is skipped if condition is True or returns True.

  • reason (str) – the reason to be put into the test report.

Raises

SkipTest – to skip the test if condition is or returns True.

htf.stacktrace

Every time the decorated function is called, the call stack will be printed.

@stacktrace
def function():
    pass

function()  # will print(the call stack to stdout)
htf.stacktrace(func)

The @stacktrace decorator decorates a method so that its call stack is printed to stdout every time it is called. This is useful for debugging.

htf.tags

Attach a tag to tests, fixtures or classes.

htf.tags(*tags)

Tag a test or class.

Parameters

*tags – the tags to be used

htf.timed

Ensure ending of a method or function within a given time limit.

@timed(limit=0.1)
def decorated_method_that_fails():
    time.sleep(0.2)

@timed(limit=1.0)
def decorated_method_that_does_not_fail():
    time.sleep(0.2)
htf.timed(limit)

Decorate a method to ensure that it ends within a given time limit.

Parameters

limit (float) – the time limit in seconds.