API Documentation

Testing Utilities

class slash.Test(test_method_name, fixture_store, fixture_namespace, variation)

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

after()

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

before()

Gets called before each separate case generated from this test class

run()

Warning

Not to be overriden

slash.parametrize(parameter_name, values)

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.

slash.core.fixtures.parameters.toggle(param_name)

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

Note

Also available for import as slash.parameters.toggle

slash.core.fixtures.parameters.iterate(**kwargs)

slash.abstract_test_class(cls)

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

Assertions

slash.assert_raises(exception_class, msg=None)

Ensures a subclass of ARG1 leaves the wrapped context:

>>> with assert_raises(AttributeError):
...     raise AttributeError()

slash.assert_almost_equal(a, b, delta=1e-08)

Asserts that abs(a - b) <= delta

Cleanups

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.

Parameters:

• 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)

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

slash.add_success_only_cleanup(_func, *args, **kwargs)

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

slash.get_current_cleanup_phase()

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

slash.is_in_cleanup()

Returns True if the session is currently performing any cleanups

Skips

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

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)

A decorator for skipping methods and classes

slash.skip_test(*args)

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

slash.register_skip_exception(exception_type)

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

Note

this must be called within an active session

Tags

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

Decorator for tagging tests

Fixtures

slash.fixture(func=None, name=None, scope=None, autouse=False)

slash.yield_fixture(func=None, **kw)

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)

A utility for generating parametrization values from a generator:

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

Note

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

slash.nofixtures()

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

slash.use(real_fixture_name)

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):
...    ...

Requirements

slash.requires(req, message=None)

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

Warnings

class slash.warnings.SessionWarnings

Holds all warnings emitted during the session

__init__()

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

__iter__()

Iterates through stored warnings

__weakref__

list of weak references to the object (if defined)

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

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.

slash.ignore_warnings(category=CustomWarningCategory)

Note

Filter arguments are treated as having an and logical relationship.

Note

Calling ignore_warnings() with no arguments will ignore all warnings

Hooks

slash.hooks.register(func)

A shortcut for registering hook functions by their names

Plugins

slash.plugins.active(plugin_class)

Decorator for automatically installing and activating a plugin upon definition

slash.plugins.parallel_mode(mode)

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)

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.

Note

All keyword arguments are forwarded to gossip’s register API

slash.plugins.register_if(condition)

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

class slash.plugins.PluginInterface

This class represents the base interface needed from plugin classes.

activate()

Called when the plugin is activated

configure_argument_parser(parser)

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

configure_from_parsed_args(args)

Called after successful parsing of command-line arguments

current_config

Returns configuration object for plugin

deactivate()

Called when the plugin is deactivated

Note

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.

get_config()

Use get_default_config() instead.

Deprecated since version 1.5.0.

get_default_config()

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

get_description()

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

get_name()

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

activate(plugin)

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

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

activate_later(plugin)

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

See also

activate_pending_plugins()

activate_pending_plugins()

Activates all plugins queued with activate_later()

deactivate(plugin)

Deactivates a plugin, unregistering all of its hook callbacks

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

deactivate_later(plugin)

Removes a plugin from the set of plugins pending activation.

See also

activate_pending_plugins()

discover()

Iterates over all search paths and loads plugins

get_active_plugins()

Returns a dict mapping plugin names to currently active plugins

get_future_active_plugins()

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

get_installed_plugins(include_internals=True)

Returns a dict mapping plugin names to currently installed plugins

get_plugin(plugin_name)

Retrieves a registered plugin by name, or raises a LookupError

install(plugin, activate=False, activate_later=False, is_internal=False)

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

is_internal_plugin(plugin)

Returns rather installed plugin is internal plugin

uninstall(plugin)

Uninstalls a plugin

uninstall_all()

Uninstalls all installed plugins

Logging

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

should_colorize(record)

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

get_color(record)

Returns the color for this record.

class slash.log.ConsoleHandler(**kw)

emit(record)

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

format(record)

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

emit(record)

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)

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(record)

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)

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)

should_handle(record)

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

slash.log.add_log_handler(handler)

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

slash.log.set_log_color(logger_name, level, color)

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

Exceptions

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

Context manager handling exceptions that are raised within it

Parameters:

• 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

Note

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

slash.allowing_exceptions(exception_class, msg=None)

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)

Associates a mark with a given value to the exception e

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

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.

slash.exception_handling.noswallow(exception)

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

slash.exception_handling.mark_exception_fatal(exception)

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

slash.exception_handling.get_exception_swallowing_context(report_to_sentry=True)

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

slash.exception_handling.inhibit_unhandled_exception_traceback(exception)

Causes this exception to inhibit console tracback

Misc. Utilities

slash.repeat(num_repetitions)

Marks a test to be repeated multiple times when run

Internals

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

Represents a slash session

get_total_num_tests()

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)

Runs tests from an iterable using the current session

class slash.core.metadata.Metadata(factory, test)

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

address

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

get_address(raw_params=False)

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

test_index1

Same as test_index0, only 1-based

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

exception

Deprecated since version 1.2.3: Use error.exception_str

exception_attributes

Deprecated since version 1.5.0.

func_name

Function name from which the error was raised

get_detailed_traceback_str()

Returns a formatted traceback string for the exception caught

lineno

Line number from which the error was raised

mark_fatal()

Marks this error as fatal, causing session termination

class slash.core.result.Result(test_metadata=None)

Represents a single result for a test which was run

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

Adds a failure to the result

add_exception(exc_info=None)

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

add_extra_log_path(path)

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)

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

get_additional_details

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

get_duration()

Returns the test duration time as timedelta object

Returns:timedelta

get_errors()

Returns the list of errors recorded for this result

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

get_failures()

Returns the list of failures recorded for this result

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

get_log_dir()

Returns log’s directory.

get_log_path()

Returns log path

get_log_paths()

Returns a list of all log paths

is_just_failure()

Indicates this is a pure failure, without errors involved

set_log_path(path)

Set log path

set_test_detail(key, value)

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

class slash.core.result.SessionResults(session)

current

Obtains the currently running result, if exists

Otherwise, returns the global result object

get_result(test)

Returns the result stored belonging to a given test

has_fatal_errors()

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

is_interrupted()

Indicates if this session was interrupted

is_success(allow_skips=False)

Indicates whether this run is successful

Parameters:allow_skips – Whether to consider skips as unsuccessful

iter_all_errors()

Iterates over all results which have errors

yields tuples of the form (result, errors_list)

iter_all_failures()

Iterates over all results which have failures

yields tuples of the form (result, failure_list)

iter_all_results()

Iterates over all results, ending with the global result object

iter_test_results()

Iterates over results belonging to tests

class slash.core.details.Details(set_callback=None)

append(key, value)

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

set(key, value)

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