teres — Welcome to Teres’s documentation!

Teres is a library for reporting results from tests written in python. So far it provides two handler classes teres.handlers.LoggingHandler and teres.bkr_handlers.ThinBkrHandler for reporting to stdout and to beaker lab controller.

Constraints

If using teres module in code together with os.fork, the teres module must be used in the same process where it’s imported first (main process). This is caused by cleanup which is called at the end of python process and ensures, that all logs are correctly reported. The cleanup however ends tests only in the main process, enabling usage of os.fork.

The API

The teres module provides a Reporter class that defines the API for the end user. Internally Reporeter can register multiple handlers thaking care of actual reporting.

class teres.Reporter

This is the class that provides the API. It hase to be initialized with set of handlers in a similar manner as python logging interface. To get an instance of the Reporter class use get_reporter() method.

get_reporter()

Since Reporter class is designed as a singleton (there can be only one instance of this class) initializing it without using this method can lead to undefined behavior. (This is the only supported way of getting the class instance.)

add_handler(handler)

Add handler to the reporter class.

remove_handler(handler)

Remove specified handler from reporter.

log(result, msg[, flags=None])

Report message with specific result level, msg. flags are optional and could depend on handlers. The result level can be one of the following constants ERROR, FAIL , PASS, FILE, INFO, DEBUG, NONE.

log_error(msg[, flags=None])

Report a message with level ERROR.

log_fail(msg[, flags=None])

Report a message with level FAIL.

log_pass(msg[, flags=None])

Report a message with level PASS.

log_info(msg[, flags=None])

Report a message with level INFO.

log_debug(msg[, flags=None])

Report a message with level DEBUG.

send_file(logfile[, logname=None[, msg=None[, flags=None]]])

Report a log file. The logfile argument can be a path to a log file stored on the filesystem or a file like object. In case of file like object is passed the read permissions are mandatory. The logname arguments provides custom log name.

test_end(clean_end=True)

Flush results from all handlers and clean up.

class teres.Handler([result=INFO[, process_logs=True]])

The Handler is an abstract class for implementing handlers used by Reporter.

Parameters:
  • result – Set result level. Messages with lower level will be ignored.
  • process_logs (bool) – Setting this to False log processing can be completely disabled.
result

This attribute contains the default result level.

process_logs

Boolean value that indicates if log files should be processed.

emit(record)

Decides whether we are reporting a result or a file and executes the correct routine to process the record.

_emit_log(record)

Take care of logging a message.

_emit_file(record)

Take care of processing a log file.

close()

Flush all pending files and messages. Clean up.

handlers

This handler class supports reporting using python logging library. Messages are simple redirected to logging and log files are copied to destination specified during the initialization.

class teres.handlers.LoggingHandler(name, handlers[, result=teres.INFO[, dest="/tmp/"]])

When creating an instance of this class directory called name is created at dest to store log files. If dest is set to None, files are only recorded and not copied. The result level is translated into python logging level and set as logging level.

bkr_handlers

class teres.bkr_handlers.ThinBkrHandler([result=teres.INFO[, task_log_name="testout.log"[, task_log_dir="/tmp/"[, recipe_id=None[, lab_controller_url=None[, disable_subtasks=False[, flush_delay=15[, report_overall=None]]]]]]]])

This handler class supports reporting to the beaker lab controller using its API. This includes converting teres result levels to those of a beaker, reporting the results, uploading log files.

List of parameters:

Parameters:
  • result_level – Default report level.
  • task_log_name (str) – The name of the log file to store all test results.
  • task_log_dir (str) – Log directory.
  • recipe_id (str) – ID of a recipe running in beaker.
  • lab_controller_url (str) – URL for communitcating with beaker.
  • disable_subtasks (bool) – This parameter can completely disable creation of subtasks in beaker.
  • flush_delay (int) – Delay between flushing the task log.
  • report_overall (str) – Create subtask result with the overall result.

If recipe_id and lab_controller_url aren’t provided constructor tries to get the values from environment variables as it is defined in beaker API for alternative harness.

To allow the user to modify results in beaker web interface one have to use flags. Flags are passed as a dict with keys as flags defined in the module and values True, False, None or a value specific for the flag.

List of flags:

  • TASK_LOG_FILE - This is a boolean flag indicating that provided log file should be sent to the task. teres.Reporter.send_file()
  • SUBTASK_RESULT - This flag is used to create new subtask result in beaker web ui. It is accepted by log methods. teres.Reporter
  • SCORE - This is used by logging functions to set score while creating subtask result. Integer value is mandatory. teres.Reporter
  • SUBTASK_LOG_FILE - This flag accepts optional value of result url to send file to specific subtask result. teres.Reporter.send_file()
  • DEFAULT_LOG_DEST - This boolean flag indicates that all following log files should be stored to this subtask by default. This can be overridden by TASK_LOG_FILE and SUBTASK_LOG_FILE flags and the default destination can be changed by using this flag again. teres.Reporter
teres.bkr_handlers._emit_file(record)

This method is called from teres.Reporter and stores the record and its type in the queue. teres.bkr_handlers._thread_loop() continuously reads from this queue and calls teres.bkr_handlers._thread_emit_file() or teres.bkr_handlers._thread_emit_log() depending on the record type.

teres.bkr_handlers._emit_log(record)

This method is called from teres.Reporter and stores the record and its type in the queue. teres.bkr_handlers._thread_loop() continuously reads from this queue and calls teres.bkr_handlers._thread_emit_file() or teres.bkr_handlers._thread_emit_log() depending on the record type.

teres.bkr_handlers._thread_emit_file(record)

Through the record parameter it accepts flags that can modify the destination of the log file sent to beaker. Without any flags the file is attached to the task result. This default path can be changed to any subtask result by using DEFAULT_LOG_DEST flag.

teres.bkr_handlers._thread_emit_log(record)

The message passed to this method is simply stored in the task log file which is periodically synced with beaker.

teres.bkr_handlers.reset_log_dest()

This method resets default log destination to task result instead of particular subtask result.