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.
- 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 throughvalues
.
- 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
Assertions¶
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)[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.skip_test(*args)[source]¶
Skips the current test execution by raising a
slash.exceptions.SkipTest
exception. It can optionally receive a reason argument.
Fixtures¶
- 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
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
Requirements¶
Warnings¶
- class slash.warnings.SessionWarnings[source]¶
Holds all warnings emitted during the session
- __weakref__¶
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 withre.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¶
Plugins¶
- slash.plugins.active(plugin_class)[source]¶
Decorator for automatically installing and activating a plugin upon definition
- slash.plugins.parallel_mode(mode)[source]¶
Marks compatibility of a specific plugin to parallel execution.
- Parameters:
mode – Can be either
disabled
,enabled
,parent-only
orchild-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.Note
All keyword arguments are forwarded to gossip’s
register
API
- 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.
- configure_argument_parser(parser)[source]¶
Gives a chance to the plugin to add options received from command-line
- property current_config¶
Returns configuration object for plugin
- 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]¶
Use
get_default_config()
instead.Deprecated since version 1.5.0.
- get_default_config()[source]¶
Optional: should return a dictionary or a confetti object which will be placed under
slash.config.plugin_config.<plugin_name>
- class slash.plugins.plugin_manager.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()
See also
- 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.
See also
- get_future_active_plugins()[source]¶
Returns a dictionary of plugins intended to be active once the ‘pending activation’ mechanism is finished
- get_installed_plugins(include_internals=True)[source]¶
Returns a dict mapping plugin names to currently installed plugins
- 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 fromslash.plugins.PluginInterface
.
Logging¶
- class slash.log.ColorizedFileHandler(filename, mode='a', encoding=None, level=0, format_string=None, delay=False, filter=None, bubble=False)[source]¶
- class slash.log.ConsoleHandler(**kw)[source]¶
- default_format_string = '[{record.time:%Y-%m-%d %H:%M:%S}] {record.message}'¶
a class attribute for the default format string to use if the constructor was invoked with None.
- emit(record)[source]¶
Emit the specified logging record. This should take the record and deliver it to whereever the handler sends formatted log records.
- format(record)[source]¶
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.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¶
contains the path for the session logs
- test_log_path¶
contains the path for the current test logs
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.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.
- 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
Misc. Utilities¶
Internals¶
- class slash.core.session.Session(reporter=None, console_stream=None)[source]¶
Represents a slash session
- results¶
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__
- property 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¶
Address string to identify the test inside the file from which it was loaded
- get_address(raw_params=False)[source]¶
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¶
The test’s unique id
- module_name¶
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
- property test_index1¶
Same as
test_index0
, only 1-based
- class slash.core.error.Error(msg=None, exc_info=None, frame_correction=0)[source]¶
- property exception¶
Deprecated since version 1.2.3: Use error.exception_str
- property exception_attributes¶
Deprecated since version 1.5.0.
- property func_name¶
Function name from which the error was raised
- property lineno¶
Line number from which the error was raised
- 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
- 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, append=True)[source]¶
Adds a failure to the result
- data¶
dictionary to be use by tests and plugins to store result-related information for later analysis
- details¶
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_errors()[source]¶
Returns the list of errors recorded for this result
- Returns:
a list of
slash.core.error.Error
objects
- get_failures()[source]¶
Returns the list of failures recorded for this result
- Returns:
a list of
slash.core.error.Error
objects
- class slash.core.result.SessionResults(session)[source]¶
- property current¶
Obtains the currently running result, if exists
Otherwise, returns the global result object
- has_fatal_errors()[source]¶
Indicates whether any result has an error marked as fatal (causing the session to terminate)
- is_success(allow_skips=False)[source]¶
Indicates whether this run is successful
- Parameters:
allow_skips – Whether to consider skips as unsuccessful
- iter_all_errors()[source]¶
Iterates over all results which have errors
yields tuples of the form (result, errors_list)