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.

after()[source]

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

before()[source]

Gets called before each separate case generated from this test class

run()[source]

Warning

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.

slash.core.fixtures.parameters.toggle(param_name)[source]

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

Note

Also available for import as slash.parameters.toggle

slash.core.fixtures.parameters.iterate(**kwargs)[source]
slash.abstract_test_class(cls)[source]

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

Cleanups

slash.add_cleanup(*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)[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

Skips

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

slash.skip_test(*args)[source]

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)[source]

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>)[source]

Decorator for tagging tests

Fixtures

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)[source]

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)[source]

Allows tests to use fixtures under different names

def test_something(m: use(‘microwave’)):
...

Requirements

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

Warnings

class slash.warnings.SessionWarnings[source]

Holds all warnings emitted during the session

__iter__()[source]

Iterates through stored warnings

__weakref__

list of weak references to the object (if defined)

Hooks

slash.hooks.add_custom_hook(*args, **kwargs)[source]
Adds an additional hook to the set of available hooks

Deprecated since version 0.6.0: Use gossip instead

slash.hooks.ensure_custom_hook(*args, **kwargs)[source]
Like add_custom_hook(), only forgives if the hook already exists

Deprecated since version 0.6.0: Use gossip instead

slash.hooks.get_custom_hook_names(*args, **kwargs)[source]
Retrieves the names of all custom hooks currently installed

Deprecated since version 0.6.0: Use gossip instead

slash.hooks.get_hook_by_name(*args, **kwargs)[source]
Returns a hook (if exists) by its name, otherwise returns None

Deprecated since version 0.6.0: Use gossip instead

slash.hooks.register(func)[source]

A shortcut for registering hook functions by their names

slash.hooks.remove_custom_hook(*args, **kwargs)[source]
Removes a hook from the set of available hooks

Deprecated since version 0.6.0: Use gossip instead

Plugins

slash.plugins.active(plugin_class)[source]

Decorator for automatically installing and activating a plugin upon definition

slash.plugins.registers_on(hook_name)[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.

slash.plugins.register_if(condition)[source]

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.

activate()[source]

Called when the plugin is activated

configure_argument_parser(parser)[source]

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

configure_from_parsed_args(args)[source]

Called after successful parsing of command-line arguments

deactivate()[source]

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()[source]

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

get_description()[source]

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()[source]

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.PluginManager[source]
activate(plugin)[source]

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

Parameters:plugin – either a plugin object or a plugin name
activate_later(plugin)[source]

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

activate_pending_plugins()[source]

Activates all plugins queued with activate_later()

deactivate(plugin)[source]

Deactivates a plugin, unregistering all of its hook callbacks

Parameters:plugin – either a plugin object or a plugin name
deactivate_later(plugin)[source]

Removes a plugin from the set of plugins pending activation.

discover()[source]

Iterates over all search paths and loads plugins

get_active_plugins()[source]

Returns a dict mapping plugin names to currently active plugins

get_future_active_plugins()[source]

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

get_installed_plugins()[source]

Returns a dict mapping plugin names to currently installed plugins

get_plugin(plugin_name)[source]

Retrieves a registered plugin by name, or raises a LookupError

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

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

uninstall(plugin)[source]

Uninstalls a plugin

uninstall_all()[source]

Uninstalls all installed plugins

Logging

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

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

slash.log.add_log_handler(handler)[source]

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

Exceptions

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

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

slash.exception_handling.noswallow(exception)[source]

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

slash.exception_handling.mark_exception_fatal(exception)[source]

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(*args, **kwds)[source]

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

Misc. Utilities

slash.repeat(num_repetitions)[source]

Marks a test to be repeated multiple times when run

Internals

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

Represents a slash session

get_total_num_tests()[source]

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__

address = None

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

address_in_file = None

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

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.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)[source]

Adds a failure to the result

add_exception(exc_info=None)[source]

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

add_extra_log_path(path)[source]

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

get_log_dir()[source]

Returns log’s directory.

get_log_path()[source]

Returns log path

get_log_paths()[source]

Returns a list of all log paths

is_just_failure()[source]

Indicates this is a pure failure, without errors involved

set_log_path(path)[source]

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