PyDocs

proboscis

proboscis.test(home=None, **kwargs)

Decorates a test class or function to cause Proboscis to run it.

The behavior differs depending the target:

• If put on a stand-alone function, the function will run by itself.

• If put on a class inheriting unittest.TestCase, then the class will run just like a normal unittest class by using the method names and instantiate a new instance of the class for each test method.

• If the class does not inherit from unittest.TestCase, the class will be instantiated once and this instance will be passed to each method decorated with @test (this increases encapsulation over using class fields as the instance can not be accessed outside of its methods).

  Note that due to how decorators work its impossible to know if a function is or is not part of a class; thus if a class method is decorated with test but its class is not then ProboscisTestMethodNotDecorated will be raised.

Parameters:

• groups – A list of strings representing the groups this test method or class belongs to. By default this is an empty list.
• depends_on – A list of test functions or classes which must run before this test. By default this is an empty list.
• depends_on_groups – A list of strings each naming a group that must run before this test. By default this is an empty list.
• enabled – By default, true. If set to false this test will not run.
• always_run – If true this test will run even if the tests listed in depends_on or depends_on_groups have failed.

proboscis.before_class(home=None, **kwargs)

Like @test but indicates this should run before other class methods.

All of the arguments sent to @test work with this decorator as well.

proboscis.after_class(home=None, **kwargs)

Like @test but indicates this should run after other class methods.

All of the arguments sent to @test work with this decorator as well.

This will be skipped if a class method test fails; set always_run if that is not desired. See issue #5.

class proboscis.TestProgram(registry=<proboscis.core.TestRegistry object at 0x110f440d0>, groups=None, testLoader=None, config=None, plugins=None, env=None, testRunner=None, stream=None, argv=None, *args, **kwargs)

Bases: nose.core.TestProgram

Use this to run Proboscis.

Translates the Proboscis test registry into types used by Nose or unittest in order to run the program.

Most arguments to this are simply passed to Nose or unittest’s TestProgram class.

For most cases using the default arguments works fine.

Parameters:

• registry – The test registry to use. If unset uses the default global registry.
• groups – A list of strings representing the groups of tests to run. The list is added to by parsing the argv argument. If unset then all groups are run.
• testLoader – The test loader. By default, its unittest.TestLoader.
• config – The config passed to Nose or unittest.TestProgram. The config determines things such as plugins or output streams, so it may be necessary to create this for advanced use cases.
• plugins – Nose plugins. Similar to config it may be necessary to set this in an advanced setup.
• env – By default is os.environ. This is used only by Nose.
• testRunner – By default Proboscis uses its own. If this is set however care must be taken to avoid breaking Proboscis’s automatic skipping of tests on dependency failures. In particular, _makeResult must return a subclass of proboscis.TestResult which calls proboscis.TestResult.onError at the start of the addFailure and addError methods.
• stream – By default this is standard out.
• argv – By default this is sys.argv. Proboscis parses this for the –group argument.

create_test_suite_from_entries(config, cases)

Creates a suite runnable by unittest.

extract_groups_from_argv(argv, groups)

Given argv, records the “–group” options.

Parameters:

• argv – A list of arguments, such as sys.argv.
• groups – A list of strings for each group to run which is added to.

Returns a copy of param argv with the –group options removed. This is useful if argv needs to be passed to another program such as Nose.

run_and_exit()

Calls unittest or Nose to run all tests.

unittest will call sys.exit on completion.

show_plan()

Prints information on test entries and the order they will run.

test_suite

class proboscis.SkipTest

Bases: nose.plugins.skip.SkipTest

Raise this to skip a test. If Nose is available its SkipTest is used. Otherwise Proboscis creates its own which class that calls unittest.TestCase.skipTest. If that method isn’t available (anything under 2.7) then skipping does not work and test errors are presented.

proboscis.register(**kwargs)

Registers a test in proboscis’s default registry.

Parameters:home – The target class or function.

This also allows all of the parameters used by the @test decorator.

This function works differently than a decorator as it allows the class or function which is being registered to appear in the same call as all of the options.

Its designed to make it easier to register class or functions with Proboscis after they’re defined.

proboscis.factory(func=None, **kwargs)

Decorates a function which returns new instances of Test classes.

class proboscis.TestRegistry

Bases: object

Stores test information.

All of Proboscis’s decorators (@test, @before_class, etc) and the register function use a default instance of this class, however its also possible to instantiate multiple copies and add tests to them directly.

ensure_group_exists(group_name)

Adds the group to the registry if it does not exist.

Parameters:group_name – The group to create.

get_group(group_name)

Returns a TestGroup given its name.

Parameters:group_name – Group to return.

register(test_home=None, **kwargs)

Registers a bit of code (or nothing) to be run / ordered as a test.

Registering a test with nothing allows for the creation of groups of groups, which can be useful for organization.

When proboscis.register is called it chains to this method bound to the global default registry.

register_factory(func)

Turns a function into a Proboscis test instance factory.

A factory returns a list of test class instances. Proboscis runs all factories at start up and sorts the instances like normal tests.

Parameters:func – the function to be added.

reset()

Wipes the registry.

class proboscis.ProboscisTestMethodClassNotDecorated

Bases: exceptions.Exception

This denotes a very common error that seems somewhat unavoidable due to the fact it isn’t possible to know if a method is bound or not in Python when you decorate it.

proboscis.asserts

Assert functions with a parameter order of actual_value, expected_value.

This module contains many stand-ins for functions in Nose.tools. It is also a clone of TestNG’s Assert class with the static methods changed to functions, and the term “equals” changed to simply “equal” to be more Pythonic.

There are also a few original assertions methods and the class Check.

This module should be preferred when Nose is not always available.

proboscis.asserts.assert_equal(actual, expected, message=None)

Asserts that the two values are equal.

Parameters:

• actual – The actual value.
• expected – The expected value.
• message – A message to show in the event of a failure.

proboscis.asserts.assert_false(condition, message=None)

Asserts that the given condition is false.

Parameters:

• condition – Must be true.
• message – A message to show in the event of failure.

proboscis.asserts.assert_is(actual, expected, message=None)

Asserts that the two variables share the same identity.

Parameters:

• actual – A variable which has the actual identity.
• expected – The variable which has the expected variable.
• message – A message to show in the event of failure.

proboscis.asserts.assert_is_none(value, message=None)

Asserts that the given value is None.

Parameters:

• value – The value which is tested for nothingness.
• message – A message to show in the event of failure.

proboscis.asserts.assert_is_not(actual, expected, message=None)

Asserts that the two variables has different identities.

Parameters:

• actual – A variable which has the actual identity.
• expected – A variable which has the expected identity.
• message – The assertion message if the variables share an identity.

proboscis.asserts.assert_is_not_none(value, message=None)

Asserts that a value is anything other than None.

Parameters:

• value – A variable which is expected to be anything other than None.
• message – The assertion message if the variable is None.

proboscis.asserts.assert_not_equal(actual, expected, message=None)

Asserts that the two values are not equal.

Parameters:

• actual – The actual value.
• expected – The expected value.
• message – The assertion message if the variables are equal.

proboscis.asserts.assert_true(condition, message=None)

Asserts that the given value is True.

Parameters:

• condition – A value that must be True.
• message – The assertion message if the value is not True.

proboscis.asserts.assert_raises(exception_type, function, *args, **kwargs)

Calls function and fails the test if an exception is not raised.

Unlike nose.Tool’s assert_raises or TestCase.assertRaises the given exception type must match the exactly: if the raised exception is a subclass the test will fail. For example, it fails if the exception_type param is “Exception” but “RuntimeException” is raised. To be less demanding use assert_raises_instance.

Parameters:

• exception_type – The exact type of exception to be raised.
• function – The function to call, followed by its arguments.

proboscis.asserts.assert_raises_instance(exception_type, function, *args, **kwargs)

Calls function and fails the test if an exception is not raised.

The exception thrown must only be an instance of the given type. This means if “Exception” is expected but “RuntimeException” is raised the test will still pass. For a stricter function see assert_raises.

Parameters:

• exception_type – The expected exception type.
• function – The function to call, followed by its arguments.

proboscis.asserts.fail(message)

Fails a test.

Parameters:message – The message to display.

Unlike the other functions in this module the message argument is required.

class proboscis.asserts.Check

Bases: object

Used to test and record multiple failing asserts in a single function.

Usually its best to write numerous small methods with a single assert in each one, but sometimes this ideal isn’t possible and multiple asserts must be made in the same function.

In some cases, such as when all properties of a returned object are being interrogated, these asserts do not depend on each other and having the test stop after the first one can be a bother if the task was run on a CI server or somewhere else.

This class solves that by saving any assert failures and raising one giant assert at the end of a with block.

To use it, write something like:

some_obj = ...
with Check() as check:
    check.equal(some_obj.a, "A")
    check.equal(some_obj.b, "B")
    check.equal(some_obj.c, "C")

At the end of the with block if any checks failed one assertion will be raised containing inside it the stack traces for each assertion.

If instances are not used in a with block any failed assert will raise instantly.

equal(*args, **kwargs)

Identical to assert_equal.

fail(*args, **kwargs)

Identical to fail.

false(*args, **kwargs)

Identical to assert_false.

is_none(*args, **kwargs)

Identical to assert_is_none.

is_not(*args, **kwargs)

Identical to assert_is_not.

is_not_none(*args, **kwargs)

Identical to assert_is_not_none.

is_same(*args, **kwargs)

Identical to assert_is.

not_equal(*args, **kwargs)

Identical to assert_not_equal.

raises(*args, **kwargs)

Identical to assert_raises.

raises_instance(*args, **kwargs)

Identical to assert_raises_instance.

true(*args, **kwargs)

Identical to assert_true.