API Documentation

Testing Utilities

class slash.Test(test_method_name, fixture_store, fixture_namespace, variation)[source]

This is a base class for implementing unittest-style test classes.


Gets called after each separate case from this test class executed, assuming before() was successful.


Gets called before each separate case generated from this test class



Not to be overriden

slash.parametrize(parameter_name, values)[source]

Decorator to create multiple test cases out of a single function or module, where the cases vary by the value of parameter_name, as iterated through values.


A shortcut for slash.parametrize(param_name, [True, False])


Also available for import as slash.parameters.toggle


Marks a class as abstract, thus meaning it is not to be run directly, but rather via a subclass.


slash.assert_raises(exception_class, msg=None)[source]

Ensures a subclass of ARG1 leaves the wrapped context:

>>> with assert_raises(AttributeError):
...     raise AttributeError()
slash.assert_almost_equal(a, b, delta=1e-08)[source]

Asserts that abs(a - b) <= delta


slash.add_cleanup(self, _func, *args, **kwargs)

Adds a cleanup function to the cleanup stack. Cleanups are executed in a LIFO order.

Positional arguments and keywords are passed to the cleanup function when called.

  • critical – If True, this cleanup will take place even when tests are interrupted by the user (Using Ctrl+C for instance)
  • success_only – If True, execute this cleanup only if no errors are encountered
  • scope – Scope at the end of which this cleanup will be executed
  • args – positional arguments to pass to the cleanup function
  • kwargs – keyword arguments to pass to the cleanup function
slash.add_critical_cleanup(_func, *args, **kwargs)[source]

Same as add_cleanup(), only the cleanup will be called even on interrupted tests

slash.add_success_only_cleanup(_func, *args, **kwargs)[source]

Same as add_cleanup(), only the cleanup will be called only if the test succeeds


Returns the current cleanup stage the session is currently in. This can return any one of the cleanup scopes supported by Slash, or None if no cleanups are currently in progress


Returns True if the session is currently performing any cleanups


class slash.exceptions.SkipTest(reason='Test skipped')[source]

This exception should be raised in order to interrupt the execution of the currently running test, marking it as skipped

slash.skipped(thing, reason=None)[source]

A decorator for skipping methods and classes


Skips the current test execution by raising a slash.exceptions.SkipTest exception. It can optionally receive a reason argument.


Registers a custom exception type to be recognized a test skip. This makes the exception behave just as if the test called skip_test


this must be called within an active session


slash.tag(tag_name, tag_value=<NOTHING>)[source]

Decorator for tagging tests


slash.fixture(func=None, name=None, scope=None, autouse=False)[source]
slash.yield_fixture(func=None, **kw)[source]

Builds a fixture out of a generator. The pre-yield part of the generator is used as the setup, where the yielded value becomes the fixture value. The post-yield part is added as a cleanup:

>>> @slash.yield_fixture
... def some_fixture(arg1, arg2):
...     m = Microwave()
...     m.turn_on(wait=True)
...     yield m
...     m.turn_off()
slash.generator_fixture(func=None, **kw)[source]

A utility for generating parametrization values from a generator:

>>> @slash.generator_fixture
... def some_parameter():
...     yield first_value
...     yield second_value


A generator parameter is a shortcut for a simple parametrized fixture, so the entire iteration is exhausted during test load time


Marks the decorated function as opting out of automatic fixture deduction. Slash will not attempt to parse needed fixtures from its argument list


Allows tests to use fixtures under different names:

>>> def test_something(m: use('microwave')):
...    ...

For cosmetic purposes, you can also use use with attribute access:

>>> def test_something(m: use.microwave):
...    ...


slash.requires(req, message=None)[source]

A decorator specifying that the decorated tests requires a certain precondition in order to run

Parameters:req – Either a function receiving no arguments and returning a boolean, or a boolean specifying whether or not the requirement is met


class slash.warnings.SessionWarnings[source]

Holds all warnings emitted during the session


Initialize self. See help(type(self)) for accurate signature.


Iterates through stored warnings


list of weak references to the object (if defined)

slash.ignore_warnings(category=None, message=None, filename=None, lineno=None)[source]

Ignores warnings of specific origin (category/filename/lineno/message) during the session. Unlike Python’s default warnings.filterwarnings, the parameters are matched only if specified (not defaulting to “match all”). Message can also be a regular expression object compiled with re.compile.



Filter arguments are treated as having an and logical relationship.


Calling ignore_warnings() with no arguments will ignore all warnings



A shortcut for registering hook functions by their names



Decorator for automatically installing and activating a plugin upon definition


Marks compatibility of a specific plugin to parallel execution.

Parameters:mode – Can be either disabled, enabled, parent-only or child-only
slash.plugins.registers_on(hook_name, **kwargs)[source]

Marks the decorated plugin method to register on a custom hook, rather than the method name in the ‘slash’ group, which is the default behavior for plugins

Specifying registers_on(None) means that this is not a hook entry point at all.


All keyword arguments are forwarded to gossip’s register API


Marks the decorated plugins method to only be registered if condition is True

class slash.plugins.PluginInterface[source]

This class represents the base interface needed from plugin classes.


Called when the plugin is activated


Gives a chance to the plugin to add options received from command-line


Called after successful parsing of command-line arguments


Returns configuration object for plugin


Called when the plugin is deactivated


this method might not be called in practice, since it is not guaranteed that plugins are always deactivated upon process termination. The intention here is to make plugins friendlier to cases in which multiple sessions get established one after another, each with a different set of plugins.


Use get_default_config() instead.

Deprecated since version 1.5.0.


Optional: should return a dictionary or a confetti object which will be placed under slash.config.plugin_config.<plugin_name>


Retrieves a quick description for this plugin, mostly used in command-line help or online documentation. It is not mandatory to override this method.


Returns the name of the plugin class. This name is used to register, disable and address the plugin during runtime.

Note that the command-line switches (--with-...) are derived from this name.

Any implemented plugin must override this method.

class slash.plugins.plugin_manager.PluginManager[source]

Activates a plugin, registering its hook callbacks to their respective hooks.

Parameters:plugin – either a plugin object or a plugin name

Adds a plugin to the set of plugins pending activation. It can be remvoed from the queue with deactivate_later()


Activates all plugins queued with activate_later()


Deactivates a plugin, unregistering all of its hook callbacks

Parameters:plugin – either a plugin object or a plugin name

Removes a plugin from the set of plugins pending activation.


Iterates over all search paths and loads plugins


Returns a dict mapping plugin names to currently active plugins


Returns a dictionary of plugins intended to be active once the ‘pending activation’ mechanism is finished


Returns a dict mapping plugin names to currently installed plugins


Retrieves a registered plugin by name, or raises a LookupError

install(plugin, activate=False, activate_later=False, is_internal=False)[source]

Installs a plugin object to the plugin mechanism. plugin must be an object deriving from slash.plugins.PluginInterface.


Returns rather installed plugin is internal plugin


Uninstalls a plugin


Uninstalls all installed plugins


class slash.log.ColorizedFileHandler(filename, mode='a', encoding=None, level=0, format_string=None, delay=False, filter=None, bubble=False)[source]

Returns True if colorizing should be applied to this record. The default implementation returns True if the stream is a tty. If we are executing on Windows, colorama must be installed.

class slash.log.ColorizedHandlerMixin[source]

Returns the color for this record.

class slash.log.ConsoleHandler(**kw)[source]

Emit the specified logging record. This should take the record and deliver it to whereever the handler sends formatted log records.


Formats a record with the given formatter. If no formatter is set, the record message is returned. Generally speaking the return value is most likely a unicode string, but nothing in the handler interface requires a formatter to return a unicode string.

The combination of a handler and formatter might have the formatter return an XML element tree for example.

class slash.log.ErrorHandler[source]

Emit the specified logging record. This should take the record and deliver it to whereever the handler sends formatted log records.

class slash.log.RetainedLogHandler(*args, **kwargs)[source]

A logbook handler that retains the emitted logs in order to flush them later to a handler.

This is useful to keep logs that are emitted during session configuration phase, and not lose them from the session log


Emit the specified logging record. This should take the record and deliver it to whereever the handler sends formatted log records.

class slash.log.SessionLogging(session, console_stream=None)[source]

A context creator for logging within a session and its tests

session_log_path = None

contains the path for the session logs

test_log_path = None

contains the path for the current test logs

class slash.log.SilencedLoggersHandler(silence_logger_names)[source]

Returns True if this handler wants to handle the record. The default implementation checks the level.


Adds a log handler to be entered for sessions and for tests

slash.log.set_log_color(logger_name, level, color)[source]

Sets the color displayed in the console, according to the logger name and level


slash.exception_handling.handling_exceptions(fake_traceback=True, **kwargs)[source]

Context manager handling exceptions that are raised within it

  • passthrough_types – a tuple specifying exception types to avoid handling, raising them immediately onward
  • swallow – causes this context to swallow exceptions
  • swallow_types – causes the context to swallow exceptions of, or derived from, the specified types
  • context – An optional string describing the operation being wrapped. This will be emitted to the logs to simplify readability


certain exceptions are never swallowed - most notably KeyboardInterrupt, SystemExit, and SkipTest

slash.allowing_exceptions(exception_class, msg=None)[source]

Allow subclass of ARG1 to be raised during context:

>>> with allowing_exceptions(AttributeError):
...     raise AttributeError()
>>> with allowing_exceptions(AttributeError):
...     pass
slash.exception_handling.mark_exception(e, name, value)[source]

Associates a mark with a given value to the exception e

slash.exception_handling.get_exception_mark(e, name, default=None)[source]

Given an exception and a label name, get the value associated with that mark label. If the label does not exist on the specified exception, default is returned.


Marks an exception to prevent swallowing by slash.exception_handling.get_exception_swallowing_context(), and returns it


Causes this exception to halt the execution of the entire run.

This is useful when detecting errors that need careful examination, thus preventing further tests from altering the test subject’s state


Returns a context under which all exceptions are swallowed (ignored)


Causes this exception to inhibit console tracback

Misc. Utilities


Marks a test to be repeated multiple times when run


class slash.core.session.Session(reporter=None, console_stream=None)[source]

Represents a slash session


Returns the total number of tests expected to run in this session

results = None

an aggregate result summing all test results and the global result

slash.runner.run_tests(iterable, stop_on_error=None)[source]

Runs tests from an iterable using the current session

class slash.core.metadata.Metadata(factory, test)[source]

Class representing the metadata associated with a test object. Generally available as test.__slash__


String identifying the test, to be used when logging or displaying results in the console generally it is composed of the file path and the address inside the file

Parameters:raw_params – If True, emit the full parametrization values are interpolated into the returned string
address_in_file = None

Address string to identify the test inside the file from which it was loaded


String identifying the test, to be used when logging or displaying results in the console generally it is composed of the file path and the address inside the file

Parameters:raw_params – If True, emit the full parametrization values are interpolated into the returned string
id = None

The test’s unique id

module_name = None

The path to the file from which this test was loaded

test_index0 = None

The index of the test in the current execution, 0-based


Same as test_index0, only 1-based

class slash.core.error.Error(msg=None, exc_info=None, frame_correction=0)[source]

Deprecated since version 1.2.3: Use error.exception_str


Deprecated since version 1.5.0.


Function name from which the error was raised


Returns a formatted traceback string for the exception caught


Line number from which the error was raised


Marks this error as fatal, causing session termination

class slash.core.result.Result(test_metadata=None)[source]

Represents a single result for a test which was run

add_error(e=None, frame_correction=0, exc_info=None, append=True)[source]

Adds a failure to the result


Adds the currently active exception, assuming it wasn’t already added to a result


Add additional log path. This path will be added to the list returns by get_log_paths

add_failure(e=None, frame_correction=0, exc_info=None, append=True)[source]

Adds a failure to the result

data = None

dictionary to be use by tests and plugins to store result-related information for later analysis

details = None

a slash.core.details.Details instance for storing additional test details


Deprecated since version 0.20.0: Use result.details.all()


Returns the test duration time as timedelta object


Returns the list of errors recorded for this result

Returns:a list of slash.core.error.Error objects

Returns the list of failures recorded for this result

Returns:a list of slash.core.error.Error objects

Returns log’s directory.


Returns log path


Returns a list of all log paths


Indicates this is a pure failure, without errors involved


Set log path

set_test_detail(key, value)[source]

Adds a generic detail to this test result, which can be later inspected or used

class slash.core.result.SessionResults(session)[source]

Obtains the currently running result, if exists

Otherwise, returns the global result object


Returns the result stored belonging to a given test


Indicates whether any result has an error marked as fatal (causing the session to terminate)


Indicates if this session was interrupted


Indicates whether this run is successful

Parameters:allow_skips – Whether to consider skips as unsuccessful

Iterates over all results which have errors

yields tuples of the form (result, errors_list)


Iterates over all results which have failures

yields tuples of the form (result, failure_list)


Iterates over all results, ending with the global result object


Iterates over results belonging to tests

class slash.core.details.Details(set_callback=None)[source]
append(key, value)[source]

Appends a value to a list key, or creates it if needed

set(key, value)[source]

Sets a specific detail (by name) to a specific value