unittest — Unit testing framework

Source code:Lib/unittest/__init__.py

(If you are already familiar with the basic concepts of testing, you might wantto skip tothe list of assert methods.)

Theunittest unit testing framework was originally inspired by JUnitand has a similar flavor as major unit testing frameworks in otherlanguages. It supports test automation, sharing of setup and shutdown codefor tests, aggregation of tests into collections, and independence of thetests from the reporting framework.

To achieve this,unittest supports some important concepts in anobject-oriented way:

test fixture

Atest fixture represents the preparation needed to perform one or moretests, and any associated cleanup actions. This may involve, for example,creating temporary or proxy databases, directories, or starting a serverprocess.

test case

Atest case is the individual unit of testing. It checks for a specificresponse to a particular set of inputs.unittest provides a base class,TestCase, which may be used to create new test cases.

test suite

Atest suite is a collection of test cases, test suites, or both. It isused to aggregate tests that should be executed together.

test runner

Atest runner is a component which orchestrates the execution of testsand provides the outcome to the user. The runner may use a graphical interface,a textual interface, or return a special value to indicate the results ofexecuting the tests.

See also

Moduledoctest

Another test-support module with a very different flavor.

Simple Smalltalk Testing: With Patterns

Kent Beck’s original paper on testing frameworks using the pattern sharedbyunittest.

pytest

Third-party unittest framework with a lighter-weight syntax for writingtests. For example,assertfunc(10)==42.

The Python Testing Tools Taxonomy

An extensive list of Python testing tools including functional testingframeworks and mock object libraries.

Testing in Python Mailing List

A special-interest-group for discussion of testing, and testing tools,in Python.

The scriptTools/unittestgui/unittestgui.py in the Python source distribution isa GUI tool for test discovery and execution. This is intended largely for ease of usefor those new to unit testing. For production environments it isrecommended that tests be driven by a continuous integration system such asBuildbot,Jenkins,GitHub Actions, orAppVeyor.

Basic example

Theunittest module provides a rich set of tools for constructing andrunning tests. This section demonstrates that a small subset of the toolssuffice to meet the needs of most users.

Here is a short script to test three string methods:

importunittestclassTestStringMethods(unittest.TestCase):deftest_upper(self):self.assertEqual('foo'.upper(),'FOO')deftest_isupper(self):self.assertTrue('FOO'.isupper())self.assertFalse('Foo'.isupper())deftest_split(self):s='hello world'self.assertEqual(s.split(),['hello','world'])# check that s.split fails when the separator is not a stringwithself.assertRaises(TypeError):s.split(2)if__name__=='__main__':unittest.main()

A test case is created by subclassingunittest.TestCase. The threeindividual tests are defined with methods whose names start with the letterstest. This naming convention informs the test runner about which methodsrepresent tests.

The crux of each test is a call toassertEqual() to check for anexpected result;assertTrue() orassertFalse()to verify a condition; orassertRaises() to verify that aspecific exception gets raised. These methods are used instead of theassert statement so the test runner can accumulate all test resultsand produce a report.

ThesetUp() andtearDown() methods allow youto define instructions that will be executed before and after each test method.They are covered in more detail in the sectionOrganizing test code.

The final block shows a simple way to run the tests.unittest.main()provides a command-line interface to the test script. When run from the commandline, the above script produces an output that looks like this:

...----------------------------------------------------------------------Ran3testsin0.000sOK

Passing the-v option to your test script will instructunittest.main()to enable a higher level of verbosity, and produce the following output:

test_isupper(__main__.TestStringMethods.test_isupper)...oktest_split(__main__.TestStringMethods.test_split)...oktest_upper(__main__.TestStringMethods.test_upper)...ok----------------------------------------------------------------------Ran3testsin0.001sOK

The above examples show the most commonly usedunittest features whichare sufficient to meet many everyday testing needs. The remainder of thedocumentation explores the full feature set from first principles.

Changed in version 3.11:The behavior of returning a value from a test method (other than the defaultNone value), is now deprecated.

Command-Line Interface

The unittest module can be used from the command line to run tests frommodules, classes or even individual test methods:

python-munittesttest_module1test_module2python-munittesttest_module.TestClasspython-munittesttest_module.TestClass.test_method

You can pass in a list with any combination of module names, and fullyqualified class or method names.

Test modules can be specified by file path as well:

python-munittesttests/test_something.py

This allows you to use the shell filename completion to specify the test module.The file specified must still be importable as a module. The path is convertedto a module name by removing the ‘.py’ and converting path separators into ‘.’.If you want to execute a test file that isn’t importable as a module you shouldexecute the file directly instead.

You can run tests with more detail (higher verbosity) by passing in the -v flag:

python-munittest-vtest_module

When executed without argumentsTest Discovery is started:

python-munittest

For a list of all the command-line options:

python-munittest-h

Changed in version 3.2:In earlier versions it was only possible to run individual test methods andnot modules or classes.

Command-line options

unittest supports these command-line options:

-b,--buffer

The standard output and standard error streams are buffered during the testrun. Output during a passing test is discarded. Output is echoed normallyon test fail or error and is added to the failure messages.

-c,--catch

Control-C during the test run waits for the current test to end and thenreports all the results so far. A secondControl-C raises the normalKeyboardInterrupt exception.

SeeSignal Handling for the functions that provide this functionality.

-f,--failfast

Stop the test run on the first error or failure.

-k

Only run test methods and classes that match the pattern or substring.This option may be used multiple times, in which case all test cases thatmatch any of the given patterns are included.

Patterns that contain a wildcard character (*) are matched against thetest name usingfnmatch.fnmatchcase(); otherwise simple case-sensitivesubstring matching is used.

Patterns are matched against the fully qualified test method name asimported by the test loader.

For example,-kfoo matchesfoo_tests.SomeTest.test_something,bar_tests.SomeTest.test_foo, but notbar_tests.FooTest.test_something.

--locals

Show local variables in tracebacks.

--durationsN

Show the N slowest test cases (N=0 for all).

Added in version 3.2:The command-line options-b,-c and-f were added.

Added in version 3.5:The command-line option--locals.

Added in version 3.7:The command-line option-k.

Added in version 3.12:The command-line option--durations.

The command line can also be used for test discovery, for running all of thetests in a project or just a subset.

Test Discovery

Added in version 3.2.

Unittest supports simple test discovery. In order to be compatible with testdiscovery, all of the test files must bemodules orpackages importable from the top-level directory ofthe project (this means that their filenames must be valididentifiers).

Test discovery is implemented inTestLoader.discover(), but can also beused from the command line. The basic command-line usage is:

cdproject_directorypython-munittestdiscover

Note

As a shortcut,python-munittest is the equivalent ofpython-munittestdiscover. If you want to pass arguments to testdiscovery thediscover sub-command must be used explicitly.

Thediscover sub-command has the following options:

-v,--verbose

Verbose output

-s,--start-directorydirectory

Directory to start discovery (. default)

-p,--patternpattern

Pattern to match test files (test*.py default)

-t,--top-level-directorydirectory

Top level directory of project (defaults to start directory)

The-s,-p, and-t options can be passed inas positional arguments in that order. The following two command linesare equivalent:

python-munittestdiscover-sproject_directory-p"*_test.py"python-munittestdiscoverproject_directory"*_test.py"

As well as being a path it is possible to pass a package name, for examplemyproject.subpackage.test, as the start directory. The package name yousupply will then be imported and its location on the filesystem will be usedas the start directory.

Caution

Test discovery loads tests by importing them. Once test discovery has foundall the test files from the start directory you specify it turns the pathsinto package names to import. For examplefoo/bar/baz.py will beimported asfoo.bar.baz.

If you have a package installed globally and attempt test discovery ona different copy of the package then the importcould happen from thewrong place. If this happens test discovery will warn you and exit.

If you supply the start directory as a package name rather than apath to a directory then discover assumes that whichever location itimports from is the location you intended, so you will not get thewarning.

Test modules and packages can customize test loading and discovery by throughtheload_tests protocol.

Changed in version 3.4:Test discovery supportsnamespace packagesfor the start directory. Note that you need to specify the top leveldirectory too (e.g.python-munittestdiscover-sroot/namespace-troot).

Changed in version 3.11:unittest dropped thenamespace packagessupport in Python 3.11. It has been broken since Python 3.7. Start directory andsubdirectories containing tests must be regular package that have__init__.py file.

Directories containing start directory still can be a namespace package.In this case, you need to specify start directory as dotted package name,and target directory explicitly. For example:

# proj/  <-- current directory#   namespace/#     mypkg/#       __init__.py#       test_mypkg.pypython-munittestdiscover-snamespace.mypkg-t.

Organizing test code

The basic building blocks of unit testing aretest cases — singlescenarios that must be set up and checked for correctness. Inunittest,test cases are represented byunittest.TestCase instances.To make your own test cases you must write subclasses ofTestCase or useFunctionTestCase.

The testing code of aTestCase instance should be entirely selfcontained, such that it can be run either in isolation or in arbitrarycombination with any number of other test cases.

The simplestTestCase subclass will simply implement a test method(i.e. a method whose name starts withtest) in order to perform specifictesting code:

importunittestclassDefaultWidgetSizeTestCase(unittest.TestCase):deftest_default_widget_size(self):widget=Widget('The widget')self.assertEqual(widget.size(),(50,50))

Note that in order to test something, we use one of theassert* methodsprovided by theTestCase base class. If the test fails, anexception will be raised with an explanatory message, andunittestwill identify the test case as afailure. Any other exceptions will betreated aserrors.

Tests can be numerous, and their set-up can be repetitive. Luckily, wecan factor out set-up code by implementing a method calledsetUp(), which the testing framework will automaticallycall for every single test we run:

importunittestclassWidgetTestCase(unittest.TestCase):defsetUp(self):self.widget=Widget('The widget')deftest_default_widget_size(self):self.assertEqual(self.widget.size(),(50,50),'incorrect default size')deftest_widget_resize(self):self.widget.resize(100,150)self.assertEqual(self.widget.size(),(100,150),'wrong size after resize')

Note

The order in which the various tests will be run is determinedby sorting the test method names with respect to the built-inordering for strings.

If thesetUp() method raises an exception while the test isrunning, the framework will consider the test to have suffered an error, andthe test method will not be executed.

Similarly, we can provide atearDown() method that tidies upafter the test method has been run:

importunittestclassWidgetTestCase(unittest.TestCase):defsetUp(self):self.widget=Widget('The widget')deftearDown(self):self.widget.dispose()

IfsetUp() succeeded,tearDown() will berun whether the test method succeeded or not.

Such a working environment for the testing code is called atest fixture. A new TestCase instance is created as a uniquetest fixture used to execute each individual test method. ThussetUp(),tearDown(), and__init__()will be called once per test.

It is recommended that you use TestCase implementations to group tests togetheraccording to the features they test.unittest provides a mechanism forthis: thetest suite, represented byunittest’sTestSuite class. In most cases, callingunittest.main() will dothe right thing and collect all the module’s test cases for you and executethem.

However, should you want to customize the building of your test suite,you can do it yourself:

defsuite():suite=unittest.TestSuite()suite.addTest(WidgetTestCase('test_default_widget_size'))suite.addTest(WidgetTestCase('test_widget_resize'))returnsuiteif__name__=='__main__':runner=unittest.TextTestRunner()runner.run(suite())

You can place the definitions of test cases and test suites in the same modulesas the code they are to test (such aswidget.py), but there are severaladvantages to placing the test code in a separate module, such astest_widget.py:

  • The test module can be run standalone from the command line.

  • The test code can more easily be separated from shipped code.

  • There is less temptation to change test code to fit the code it tests withouta good reason.

  • Test code should be modified much less frequently than the code it tests.

  • Tested code can be refactored more easily.

  • Tests for modules written in C must be in separate modules anyway, so why notbe consistent?

  • If the testing strategy changes, there is no need to change the source code.

Re-using old test code

Some users will find that they have existing test code that they would like torun fromunittest, without converting every old test function to aTestCase subclass.

For this reason,unittest provides aFunctionTestCase class.This subclass ofTestCase can be used to wrap an existing testfunction. Set-up and tear-down functions can also be provided.

Given the following test function:

deftestSomething():something=makeSomething()assertsomething.nameisnotNone# ...

one can create an equivalent test case instance as follows, with optionalset-up and tear-down methods:

testcase=unittest.FunctionTestCase(testSomething,setUp=makeSomethingDB,tearDown=deleteSomethingDB)

Note

Even thoughFunctionTestCase can be used to quickly convert anexisting test base over to aunittest-based system, this approach isnot recommended. Taking the time to set up properTestCasesubclasses will make future test refactorings infinitely easier.

In some cases, the existing tests may have been written using thedoctestmodule. If so,doctest provides aDocTestSuite class that canautomatically buildunittest.TestSuite instances from the existingdoctest-based tests.

Skipping tests and expected failures

Added in version 3.1.

Unittest supports skipping individual test methods and even whole classes oftests. In addition, it supports marking a test as an “expected failure,” a testthat is broken and will fail, but shouldn’t be counted as a failure on aTestResult.

Skipping a test is simply a matter of using theskip()decoratoror one of its conditional variants, callingTestCase.skipTest() within asetUp() or test method, or raisingSkipTest directly.

Basic skipping looks like this:

classMyTestCase(unittest.TestCase):@unittest.skip("demonstrating skipping")deftest_nothing(self):self.fail("shouldn't happen")@unittest.skipIf(mylib.__version__<(1,3),"not supported in this library version")deftest_format(self):# Tests that work for only a certain version of the library.pass@unittest.skipUnless(sys.platform.startswith("win"),"requires Windows")deftest_windows_support(self):# windows specific testing codepassdeftest_maybe_skipped(self):ifnotexternal_resource_available():self.skipTest("external resource not available")# test code that depends on the external resourcepass

This is the output of running the example above in verbose mode:

test_format(__main__.MyTestCase.test_format)...skipped'not supported in this library version'test_nothing(__main__.MyTestCase.test_nothing)...skipped'demonstrating skipping'test_maybe_skipped(__main__.MyTestCase.test_maybe_skipped)...skipped'external resource not available'test_windows_support(__main__.MyTestCase.test_windows_support)...skipped'requires Windows'----------------------------------------------------------------------Ran4testsin0.005sOK(skipped=4)

Classes can be skipped just like methods:

@unittest.skip("showing class skipping")classMySkippedTestCase(unittest.TestCase):deftest_not_run(self):pass

TestCase.setUp() can also skip the test. This is useful when a resourcethat needs to be set up is not available.

Expected failures use theexpectedFailure() decorator.

classExpectedFailureTestCase(unittest.TestCase):@unittest.expectedFailuredeftest_fail(self):self.assertEqual(1,0,"broken")

It’s easy to roll your own skipping decorators by making a decorator that callsskip() on the test when it wants it to be skipped. This decorator skipsthe test unless the passed object has a certain attribute:

defskipUnlessHasattr(obj,attr):ifhasattr(obj,attr):returnlambdafunc:funcreturnunittest.skip("{!r} doesn't have{!r}".format(obj,attr))

The following decorators and exception implement test skipping and expected failures:

@unittest.skip(reason)

Unconditionally skip the decorated test.reason should describe why thetest is being skipped.

@unittest.skipIf(condition,reason)

Skip the decorated test ifcondition is true.

@unittest.skipUnless(condition,reason)

Skip the decorated test unlesscondition is true.

@unittest.expectedFailure

Mark the test as an expected failure or error. If the test fails or errorsin the test function itself (rather than in one of thetest fixturemethods) then it will be considered a success. If the test passes, it willbe considered a failure.

exceptionunittest.SkipTest(reason)

This exception is raised to skip a test.

Usually you can useTestCase.skipTest() or one of the skippingdecorators instead of raising this directly.

Skipped tests will not havesetUp() ortearDown() run around them.Skipped classes will not havesetUpClass() ortearDownClass() run.Skipped modules will not havesetUpModule() ortearDownModule() run.

Distinguishing test iterations using subtests

Added in version 3.4.

When there are very small differences among your tests, forinstance some parameters, unittest allows you to distinguish them insidethe body of a test method using thesubTest() context manager.

For example, the following test:

classNumbersTest(unittest.TestCase):deftest_even(self):"""        Test that numbers between 0 and 5 are all even.        """foriinrange(0,6):withself.subTest(i=i):self.assertEqual(i%2,0)

will produce the following output:

======================================================================FAIL:test_even(__main__.NumbersTest.test_even)(i=1)Testthatnumbersbetween0and5arealleven.----------------------------------------------------------------------Traceback(mostrecentcalllast):File"subtests.py",line11,intest_evenself.assertEqual(i%2,0)^^^^^^^^^^^^^^^^^^^^^^^^^^AssertionError:1!=0======================================================================FAIL:test_even(__main__.NumbersTest.test_even)(i=3)Testthatnumbersbetween0and5arealleven.----------------------------------------------------------------------Traceback(mostrecentcalllast):File"subtests.py",line11,intest_evenself.assertEqual(i%2,0)^^^^^^^^^^^^^^^^^^^^^^^^^^AssertionError:1!=0======================================================================FAIL:test_even(__main__.NumbersTest.test_even)(i=5)Testthatnumbersbetween0and5arealleven.----------------------------------------------------------------------Traceback(mostrecentcalllast):File"subtests.py",line11,intest_evenself.assertEqual(i%2,0)^^^^^^^^^^^^^^^^^^^^^^^^^^AssertionError:1!=0

Without using a subtest, execution would stop after the first failure,and the error would be less easy to diagnose because the value ofiwouldn’t be displayed:

======================================================================FAIL:test_even(__main__.NumbersTest.test_even)----------------------------------------------------------------------Traceback(mostrecentcalllast):File"subtests.py",line32,intest_evenself.assertEqual(i%2,0)AssertionError:1!=0

Classes and functions

This section describes in depth the API ofunittest.

Test cases

classunittest.TestCase(methodName='runTest')

Instances of theTestCase class represent the logical test unitsin theunittest universe. This class is intended to be used as a baseclass, with specific tests being implemented by concrete subclasses. This classimplements the interface needed by the test runner to allow it to drive thetests, and methods that the test code can use to check for and report variouskinds of failure.

Each instance ofTestCase will run a single base method: the methodnamedmethodName.In most uses ofTestCase, you will neither changethemethodName nor reimplement the defaultrunTest() method.

Changed in version 3.2:TestCase can be instantiated successfully without providing amethodName. This makes it easier to experiment withTestCasefrom the interactive interpreter.

TestCase instances provide three groups of methods: one group usedto run the test, another used by the test implementation to check conditionsand report failures, and some inquiry methods allowing information about thetest itself to be gathered.

Methods in the first group (running the test) are:

setUp()

Method called to prepare the test fixture. This is called immediatelybefore calling the test method; other thanAssertionError orSkipTest,any exception raised by this method will be considered an error rather thana test failure. The default implementation does nothing.

tearDown()

Method called immediately after the test method has been called and theresult recorded. This is called even if the test method raised anexception, so the implementation in subclasses may need to be particularlycareful about checking internal state. Any exception, other thanAssertionError orSkipTest, raised by this method will beconsidered an additional error rather than a test failure (thus increasingthe total number of reported errors). This method will only be called ifthesetUp() succeeds, regardless of the outcome of the test method.The default implementation does nothing.

setUpClass()

A class method called before tests in an individual class are run.setUpClass is called with the class as the only argumentand must be decorated as aclassmethod():

@classmethoddefsetUpClass(cls):...

SeeClass and Module Fixtures for more details.

Added in version 3.2.

tearDownClass()

A class method called after tests in an individual class have run.tearDownClass is called with the class as the only argumentand must be decorated as aclassmethod():

@classmethoddeftearDownClass(cls):...

SeeClass and Module Fixtures for more details.

Added in version 3.2.

run(result=None)

Run the test, collecting the result into theTestResult objectpassed asresult. Ifresult is omitted orNone, a temporaryresult object is created (by calling thedefaultTestResult()method) and used. The result object is returned torun()’scaller.

The same effect may be had by simply calling theTestCaseinstance.

Changed in version 3.3:Previous versions ofrun did not return the result. Neither didcalling an instance.

skipTest(reason)

Calling this during a test method orsetUp() skips the currenttest. SeeSkipping tests and expected failures for more information.

Added in version 3.1.

subTest(msg=None,**params)

Return a context manager which executes the enclosed code block as asubtest.msg andparams are optional, arbitrary values which aredisplayed whenever a subtest fails, allowing you to identify themclearly.

A test case can contain any number of subtest declarations, andthey can be arbitrarily nested.

SeeDistinguishing test iterations using subtests for more information.

Added in version 3.4.

debug()

Run the test without collecting the result. This allows exceptions raisedby the test to be propagated to the caller, and can be used to supportrunning tests under a debugger.

TheTestCase class provides several assert methods to check for andreport failures. The following table lists the most commonly used methods(see the tables below for more assert methods):

Method

Checks that

New in

assertEqual(a,b)

a==b

assertNotEqual(a,b)

a!=b

assertTrue(x)

bool(x)isTrue

assertFalse(x)

bool(x)isFalse

assertIs(a,b)

aisb

3.1

assertIsNot(a,b)

aisnotb

3.1

assertIsNone(x)

xisNone

3.1

assertIsNotNone(x)

xisnotNone

3.1

assertIn(a,b)

ainb

3.1

assertNotIn(a,b)

anotinb

3.1

assertIsInstance(a,b)

isinstance(a,b)

3.2

assertNotIsInstance(a,b)

notisinstance(a,b)

3.2

All the assert methods accept amsg argument that, if specified, is usedas the error message on failure (see alsolongMessage).Note that themsg keyword argument can be passed toassertRaises(),assertRaisesRegex(),assertWarns(),assertWarnsRegex()only when they are used as a context manager.

assertEqual(first,second,msg=None)

Test thatfirst andsecond are equal. If the values do notcompare equal, the test will fail.

In addition, iffirst andsecond are the exact same type and one oflist, tuple, dict, set, frozenset or str or any type that a subclassregisters withaddTypeEqualityFunc() the type-specific equalityfunction will be called in order to generate a more useful defaulterror message (see also thelist of type-specific methods).

Changed in version 3.1:Added the automatic calling of type-specific equality function.

Changed in version 3.2:assertMultiLineEqual() added as the default type equalityfunction for comparing strings.

assertNotEqual(first,second,msg=None)

Test thatfirst andsecond are not equal. If the values docompare equal, the test will fail.

assertTrue(expr,msg=None)
assertFalse(expr,msg=None)

Test thatexpr is true (or false).

Note that this is equivalent tobool(expr)isTrue and not toexprisTrue (useassertIs(expr,True) for the latter). This methodshould also be avoided when more specific methods are available (e.g.assertEqual(a,b) instead ofassertTrue(a==b)), because theyprovide a better error message in case of failure.

assertIs(first,second,msg=None)
assertIsNot(first,second,msg=None)

Test thatfirst andsecond are (or are not) the same object.

Added in version 3.1.

assertIsNone(expr,msg=None)
assertIsNotNone(expr,msg=None)

Test thatexpr is (or is not)None.

Added in version 3.1.

assertIn(member,container,msg=None)
assertNotIn(member,container,msg=None)

Test thatmember is (or is not) incontainer.

Added in version 3.1.

assertIsInstance(obj,cls,msg=None)
assertNotIsInstance(obj,cls,msg=None)

Test thatobj is (or is not) an instance ofcls (which can be aclass or a tuple of classes, as supported byisinstance()).To check for the exact type, useassertIs(type(obj),cls).

Added in version 3.2.

It is also possible to check the production of exceptions, warnings, andlog messages using the following methods:

Method

Checks that

New in

assertRaises(exc,fun,*args,**kwds)

fun(*args,**kwds) raisesexc

assertRaisesRegex(exc,r,fun,*args,**kwds)

fun(*args,**kwds) raisesexcand the message matches regexr

3.1

assertWarns(warn,fun,*args,**kwds)

fun(*args,**kwds) raiseswarn

3.2

assertWarnsRegex(warn,r,fun,*args,**kwds)

fun(*args,**kwds) raiseswarnand the message matches regexr

3.2

assertLogs(logger,level)

Thewith block logs onloggerwith minimumlevel

3.4

assertNoLogs(logger,level)

Thewith block does not log on

logger with minimumlevel

3.10

assertRaises(exception,callable,*args,**kwds)
assertRaises(exception,*,msg=None)

Test that an exception is raised whencallable is called with anypositional or keyword arguments that are also passed toassertRaises(). The test passes ifexception is raised, is anerror if another exception is raised, or fails if no exception is raised.To catch any of a group of exceptions, a tuple containing the exceptionclasses may be passed asexception.

If only theexception and possibly themsg arguments are given,return a context manager so that the code under test can be writteninline rather than as a function:

withself.assertRaises(SomeException):do_something()

When used as a context manager,assertRaises() accepts theadditional keyword argumentmsg.

The context manager will store the caught exception object in itsexception attribute. This can be useful if the intentionis to perform additional checks on the exception raised:

withself.assertRaises(SomeException)ascm:do_something()the_exception=cm.exceptionself.assertEqual(the_exception.error_code,3)

Changed in version 3.1:Added the ability to useassertRaises() as a context manager.

Changed in version 3.2:Added theexception attribute.

Changed in version 3.3:Added themsg keyword argument when used as a context manager.

assertRaisesRegex(exception,regex,callable,*args,**kwds)
assertRaisesRegex(exception,regex,*,msg=None)

LikeassertRaises() but also tests thatregex matcheson the string representation of the raised exception.regex may bea regular expression object or a string containing a regular expressionsuitable for use byre.search(). Examples:

self.assertRaisesRegex(ValueError,"invalid literal for.*XYZ'$",int,'XYZ')

or:

withself.assertRaisesRegex(ValueError,'literal'):int('XYZ')

Added in version 3.1:Added under the nameassertRaisesRegexp.

Changed in version 3.2:Renamed toassertRaisesRegex().

Changed in version 3.3:Added themsg keyword argument when used as a context manager.

assertWarns(warning,callable,*args,**kwds)
assertWarns(warning,*,msg=None)

Test that a warning is triggered whencallable is called with anypositional or keyword arguments that are also passed toassertWarns(). The test passes ifwarning is triggered andfails if it isn’t. Any exception is an error.To catch any of a group of warnings, a tuple containing the warningclasses may be passed aswarnings.

If only thewarning and possibly themsg arguments are given,return a context manager so that the code under test can be writteninline rather than as a function:

withself.assertWarns(SomeWarning):do_something()

When used as a context manager,assertWarns() accepts theadditional keyword argumentmsg.

The context manager will store the caught warning object in itswarning attribute, and the source line which triggered thewarnings in thefilename andlineno attributes.This can be useful if the intention is to perform additional checkson the warning caught:

withself.assertWarns(SomeWarning)ascm:do_something()self.assertIn('myfile.py',cm.filename)self.assertEqual(320,cm.lineno)

This method works regardless of the warning filters in place when itis called.

Added in version 3.2.

Changed in version 3.3:Added themsg keyword argument when used as a context manager.

assertWarnsRegex(warning,regex,callable,*args,**kwds)
assertWarnsRegex(warning,regex,*,msg=None)

LikeassertWarns() but also tests thatregex matches on themessage of the triggered warning.regex may be a regular expressionobject or a string containing a regular expression suitable for usebyre.search(). Example:

self.assertWarnsRegex(DeprecationWarning,r'legacy_function\(\) is deprecated',legacy_function,'XYZ')

or:

withself.assertWarnsRegex(RuntimeWarning,'unsafe frobnicating'):frobnicate('/etc/passwd')

Added in version 3.2.

Changed in version 3.3:Added themsg keyword argument when used as a context manager.

assertLogs(logger=None,level=None)

A context manager to test that at least one message is logged onthelogger or one of its children, with at least the givenlevel.

If given,logger should be alogging.Logger object or astr giving the name of a logger. The default is the rootlogger, which will catch all messages that were not blocked by anon-propagating descendent logger.

If given,level should be either a numeric logging level orits string equivalent (for example either"ERROR" orlogging.ERROR). The default islogging.INFO.

The test passes if at least one message emitted inside thewithblock matches thelogger andlevel conditions, otherwise it fails.

The object returned by the context manager is a recording helperwhich keeps tracks of the matching log messages. It has twoattributes:

records

A list oflogging.LogRecord objects of the matchinglog messages.

output

A list ofstr objects with the formatted output ofmatching messages.

Example:

withself.assertLogs('foo',level='INFO')ascm:logging.getLogger('foo').info('first message')logging.getLogger('foo.bar').error('second message')self.assertEqual(cm.output,['INFO:foo:first message','ERROR:foo.bar:second message'])

Added in version 3.4.

assertNoLogs(logger=None,level=None)

A context manager to test that no messages are logged onthelogger or one of its children, with at least the givenlevel.

If given,logger should be alogging.Logger object or astr giving the name of a logger. The default is the rootlogger, which will catch all messages.

If given,level should be either a numeric logging level orits string equivalent (for example either"ERROR" orlogging.ERROR). The default islogging.INFO.

UnlikeassertLogs(), nothing will be returned by the contextmanager.

Added in version 3.10.

There are also other methods used to perform more specific checks, such as:

Method

Checks that

New in

assertAlmostEqual(a,b)

round(a-b,7)==0

assertNotAlmostEqual(a,b)

round(a-b,7)!=0

assertGreater(a,b)

a>b

3.1

assertGreaterEqual(a,b)

a>=b

3.1

assertLess(a,b)

a<b

3.1

assertLessEqual(a,b)

a<=b

3.1

assertRegex(s,r)

r.search(s)

3.1

assertNotRegex(s,r)

notr.search(s)

3.2

assertCountEqual(a,b)

a andb have the sameelements in the same number,regardless of their order.

3.2

assertAlmostEqual(first,second,places=7,msg=None,delta=None)
assertNotAlmostEqual(first,second,places=7,msg=None,delta=None)

Test thatfirst andsecond are approximately (or not approximately)equal by computing the difference, rounding to the given number ofdecimalplaces (default 7), and comparing to zero. Note that thesemethods round the values to the given number ofdecimal places (i.e.like theround() function) and notsignificant digits.

Ifdelta is supplied instead ofplaces then the differencebetweenfirst andsecond must be less or equal to (or greater than)delta.

Supplying bothdelta andplaces raises aTypeError.

Changed in version 3.2:assertAlmostEqual() automatically considers almost equal objectsthat compare equal.assertNotAlmostEqual() automatically failsif the objects compare equal. Added thedelta keyword argument.

assertGreater(first,second,msg=None)
assertGreaterEqual(first,second,msg=None)
assertLess(first,second,msg=None)
assertLessEqual(first,second,msg=None)

Test thatfirst is respectively >, >=, < or <= thansecond dependingon the method name. If not, the test will fail:

>>>self.assertGreaterEqual(3,4)AssertionError: "3" unexpectedly not greater than or equal to "4"

Added in version 3.1.

assertRegex(text,regex,msg=None)
assertNotRegex(text,regex,msg=None)

Test that aregex search matches (or does not match)text. In caseof failure, the error message will include the pattern and thetext (orthe pattern and the part oftext that unexpectedly matched).regexmay be a regular expression object or a string containing a regularexpression suitable for use byre.search().

Added in version 3.1:Added under the nameassertRegexpMatches.

Changed in version 3.2:The methodassertRegexpMatches() has been renamed toassertRegex().

Added in version 3.2:assertNotRegex().

assertCountEqual(first,second,msg=None)

Test that sequencefirst contains the same elements assecond,regardless of their order. When they don’t, an error message listing thedifferences between the sequences will be generated.

Duplicate elements arenot ignored when comparingfirst andsecond. It verifies whether each element has the same count in bothsequences. Equivalent to:assertEqual(Counter(list(first)),Counter(list(second)))but works with sequences of unhashable objects as well.

Added in version 3.2.

TheassertEqual() method dispatches the equality check for objects ofthe same type to different type-specific methods. These methods are alreadyimplemented for most of the built-in types, but it’s also possible toregister new methods usingaddTypeEqualityFunc():

addTypeEqualityFunc(typeobj,function)

Registers a type-specific method called byassertEqual() to checkif two objects of exactly the sametypeobj (not subclasses) compareequal.function must take two positional arguments and a third msg=Nonekeyword argument just asassertEqual() does. It must raiseself.failureException(msg) when inequalitybetween the first two parameters is detected – possibly providing usefulinformation and explaining the inequalities in details in the errormessage.

Added in version 3.1.

The list of type-specific methods automatically used byassertEqual() are summarized in the following table. Notethat it’s usually not necessary to invoke these methods directly.

Method

Used to compare

New in

assertMultiLineEqual(a,b)

strings

3.1

assertSequenceEqual(a,b)

sequences

3.1

assertListEqual(a,b)

lists

3.1

assertTupleEqual(a,b)

tuples

3.1

assertSetEqual(a,b)

sets or frozensets

3.1

assertDictEqual(a,b)

dicts

3.1

assertMultiLineEqual(first,second,msg=None)

Test that the multiline stringfirst is equal to the stringsecond.When not equal a diff of the two strings highlighting the differenceswill be included in the error message. This method is used by defaultwhen comparing strings withassertEqual().

Added in version 3.1.

assertSequenceEqual(first,second,msg=None,seq_type=None)

Tests that two sequences are equal. If aseq_type is supplied, bothfirst andsecond must be instances ofseq_type or a failure willbe raised. If the sequences are different an error message isconstructed that shows the difference between the two.

This method is not called directly byassertEqual(), butit’s used to implementassertListEqual() andassertTupleEqual().

Added in version 3.1.

assertListEqual(first,second,msg=None)
assertTupleEqual(first,second,msg=None)

Tests that two lists or tuples are equal. If not, an error message isconstructed that shows only the differences between the two. An erroris also raised if either of the parameters are of the wrong type.These methods are used by default when comparing lists or tuples withassertEqual().

Added in version 3.1.

assertSetEqual(first,second,msg=None)

Tests that two sets are equal. If not, an error message is constructedthat lists the differences between the sets. This method is used bydefault when comparing sets or frozensets withassertEqual().

Fails if either offirst orsecond does not have aset.difference()method.

Added in version 3.1.

assertDictEqual(first,second,msg=None)

Test that two dictionaries are equal. If not, an error message isconstructed that shows the differences in the dictionaries. Thismethod will be used by default to compare dictionaries incalls toassertEqual().

Added in version 3.1.

Finally theTestCase provides the following methods and attributes:

fail(msg=None)

Signals a test failure unconditionally, withmsg orNone forthe error message.

failureException

This class attribute gives the exception raised by the test method. If atest framework needs to use a specialized exception, possibly to carryadditional information, it must subclass this exception in order to “playfair” with the framework. The initial value of this attribute isAssertionError.

longMessage

This class attribute determines what happens when a custom failure messageis passed as the msg argument to an assertXYY call that fails.True is the default value. In this case, the custom message is appendedto the end of the standard failure message.When set toFalse, the custom message replaces the standard message.

The class setting can be overridden in individual test methods by assigningan instance attribute, self.longMessage, toTrue orFalse beforecalling the assert methods.

The class setting gets reset before each test call.

Added in version 3.1.

maxDiff

This attribute controls the maximum length of diffs output by assertmethods that report diffs on failure. It defaults to 80*8 characters.Assert methods affected by this attribute areassertSequenceEqual() (including all the sequence comparisonmethods that delegate to it),assertDictEqual() andassertMultiLineEqual().

SettingmaxDiff toNone means that there is no maximum length ofdiffs.

Added in version 3.2.

Testing frameworks can use the following methods to collect information onthe test:

countTestCases()

Return the number of tests represented by this test object. ForTestCase instances, this will always be1.

defaultTestResult()

Return an instance of the test result class that should be used for thistest case class (if no other result instance is provided to therun() method).

ForTestCase instances, this will always be an instance ofTestResult; subclasses ofTestCase should override thisas necessary.

id()

Return a string identifying the specific test case. This is usually thefull name of the test method, including the module and class name.

shortDescription()

Returns a description of the test, orNone if no descriptionhas been provided. The default implementation of this methodreturns the first line of the test method’s docstring, if available,orNone.

Changed in version 3.1:In 3.1 this was changed to add the test name to the short descriptioneven in the presence of a docstring. This caused compatibility issueswith unittest extensions and adding the test name was moved to theTextTestResult in Python 3.2.

addCleanup(function,/,*args,**kwargs)

Add a function to be called aftertearDown() to cleanup resourcesused during the test. Functions will be called in reverse order to theorder they are added (LIFO). Theyare called with any arguments and keyword arguments passed intoaddCleanup() when they are added.

IfsetUp() fails, meaning thattearDown() is not called,then any cleanup functions added will still be called.

Added in version 3.1.

enterContext(cm)

Enter the suppliedcontext manager. If successful, alsoadd its__exit__() method as a cleanup function byaddCleanup() and return the result of the__enter__() method.

Added in version 3.11.

doCleanups()

This method is called unconditionally aftertearDown(), oraftersetUp() ifsetUp() raises an exception.

It is responsible for calling all the cleanup functions added byaddCleanup(). If you need cleanup functions to be calledprior totearDown() then you can calldoCleanups()yourself.

doCleanups() pops methods off the stack of cleanupfunctions one at a time, so it can be called at any time.

Added in version 3.1.

classmethodaddClassCleanup(function,/,*args,**kwargs)

Add a function to be called aftertearDownClass() to cleanupresources used during the test class. Functions will be called in reverseorder to the order they are added (LIFO).They are called with any arguments and keyword arguments passed intoaddClassCleanup() when they are added.

IfsetUpClass() fails, meaning thattearDownClass() is notcalled, then any cleanup functions added will still be called.

Added in version 3.8.

classmethodenterClassContext(cm)

Enter the suppliedcontext manager. If successful, alsoadd its__exit__() method as a cleanup function byaddClassCleanup() and return the result of the__enter__() method.

Added in version 3.11.

classmethoddoClassCleanups()

This method is called unconditionally aftertearDownClass(), oraftersetUpClass() ifsetUpClass() raises an exception.

It is responsible for calling all the cleanup functions added byaddClassCleanup(). If you need cleanup functions to be calledprior totearDownClass() then you can calldoClassCleanups() yourself.

doClassCleanups() pops methods off the stack of cleanupfunctions one at a time, so it can be called at any time.

Added in version 3.8.

classunittest.IsolatedAsyncioTestCase(methodName='runTest')

This class provides an API similar toTestCase and also acceptscoroutines as test functions.

Added in version 3.8.

loop_factory

Theloop_factory passed toasyncio.Runner. Overridein subclasses withasyncio.EventLoop to avoid using theasyncio policy system.

Added in version 3.13.

asyncasyncSetUp()

Method called to prepare the test fixture. This is called aftersetUp().This is called immediately before calling the test method; other thanAssertionError orSkipTest, any exception raised by this methodwill be considered an error rather than a test failure. The default implementationdoes nothing.

asyncasyncTearDown()

Method called immediately after the test method has been called and theresult recorded. This is called beforetearDown(). This is called even ifthe test method raised an exception, so the implementation in subclasses may needto be particularly careful about checking internal state. Any exception, other thanAssertionError orSkipTest, raised by this method will beconsidered an additional error rather than a test failure (thus increasingthe total number of reported errors). This method will only be called iftheasyncSetUp() succeeds, regardless of the outcome of the test method.The default implementation does nothing.

addAsyncCleanup(function,/,*args,**kwargs)

This method accepts a coroutine that can be used as a cleanup function.

asyncenterAsyncContext(cm)

Enter the suppliedasynchronous context manager. If successful,also add its__aexit__() method as a cleanup function byaddAsyncCleanup() and return the result of the__aenter__() method.

Added in version 3.11.

run(result=None)

Sets up a new event loop to run the test, collecting the result intotheTestResult object passed asresult. Ifresult isomitted orNone, a temporary result object is created (by callingthedefaultTestResult() method) and used. The result object isreturned torun()’s caller. At the end of the test all the tasksin the event loop are cancelled.

An example illustrating the order:

fromunittestimportIsolatedAsyncioTestCaseevents=[]classTest(IsolatedAsyncioTestCase):defsetUp(self):events.append("setUp")asyncdefasyncSetUp(self):self._async_connection=awaitAsyncConnection()events.append("asyncSetUp")asyncdeftest_response(self):events.append("test_response")response=awaitself._async_connection.get("https://example.com")self.assertEqual(response.status_code,200)self.addAsyncCleanup(self.on_cleanup)deftearDown(self):events.append("tearDown")asyncdefasyncTearDown(self):awaitself._async_connection.close()events.append("asyncTearDown")asyncdefon_cleanup(self):events.append("cleanup")if__name__=="__main__":unittest.main()

After running the test,events would contain["setUp","asyncSetUp","test_response","asyncTearDown","tearDown","cleanup"].

classunittest.FunctionTestCase(testFunc,setUp=None,tearDown=None,description=None)

This class implements the portion of theTestCase interface whichallows the test runner to drive the test, but does not provide the methodswhich test code can use to check and report errors. This is used to createtest cases using legacy test code, allowing it to be integrated into aunittest-based test framework.

Grouping tests

classunittest.TestSuite(tests=())

This class represents an aggregation of individual test cases and test suites.The class presents the interface needed by the test runner to allow it to be runas any other test case. Running aTestSuite instance is the same asiterating over the suite, running each test individually.

Iftests is given, it must be an iterable of individual test cases or othertest suites that will be used to build the suite initially. Additional methodsare provided to add test cases and suites to the collection later on.

TestSuite objects behave much likeTestCase objects, exceptthey do not actually implement a test. Instead, they are used to aggregatetests into groups of tests that should be run together. Some additionalmethods are available to add tests toTestSuite instances:

addTest(test)

Add aTestCase orTestSuite to the suite.

addTests(tests)

Add all the tests from an iterable ofTestCase andTestSuiteinstances to this test suite.

This is equivalent to iterating overtests, callingaddTest() foreach element.

TestSuite shares the following methods withTestCase:

run(result)

Run the tests associated with this suite, collecting the result into thetest result object passed asresult. Note that unlikeTestCase.run(),TestSuite.run() requires the result object tobe passed in.

debug()

Run the tests associated with this suite without collecting theresult. This allows exceptions raised by the test to be propagated to thecaller and can be used to support running tests under a debugger.

countTestCases()

Return the number of tests represented by this test object, including allindividual tests and sub-suites.

__iter__()

Tests grouped by aTestSuite are always accessed by iteration.Subclasses can lazily provide tests by overriding__iter__(). Notethat this method may be called several times on a single suite (forexample when counting tests or comparing for equality) so the testsreturned by repeated iterations beforeTestSuite.run() must be thesame for each call iteration. AfterTestSuite.run(), callers shouldnot rely on the tests returned by this method unless the caller uses asubclass that overridesTestSuite._removeTestAtIndex() to preservetest references.

Changed in version 3.2:In earlier versions theTestSuite accessed tests directly ratherthan through iteration, so overriding__iter__() wasn’t sufficientfor providing tests.

Changed in version 3.4:In earlier versions theTestSuite held references to eachTestCase afterTestSuite.run(). Subclasses can restorethat behavior by overridingTestSuite._removeTestAtIndex().

In the typical usage of aTestSuite object, therun() methodis invoked by aTestRunner rather than by the end-user test harness.

Loading and running tests

classunittest.TestLoader

TheTestLoader class is used to create test suites from classes andmodules. Normally, there is no need to create an instance of this class; theunittest module provides an instance that can be shared asunittest.defaultTestLoader. Using a subclass or instance, however,allows customization of some configurable properties.

TestLoader objects have the following attributes:

errors

A list of the non-fatal errors encountered while loading tests. Not resetby the loader at any point. Fatal errors are signalled by the relevantmethod raising an exception to the caller. Non-fatal errors are alsoindicated by a synthetic test that will raise the original error whenrun.

Added in version 3.5.

TestLoader objects have the following methods:

loadTestsFromTestCase(testCaseClass)

Return a suite of all test cases contained in theTestCase-derivedtestCaseClass.

A test case instance is created for each method named bygetTestCaseNames(). By default these are the method namesbeginning withtest. IfgetTestCaseNames() returns nomethods, but therunTest() method is implemented, a single testcase is created for that method instead.

loadTestsFromModule(module,*,pattern=None)

Return a suite of all test cases contained in the given module. Thismethod searchesmodule for classes derived fromTestCase andcreates an instance of the class for each test method defined for theclass.

Note

While using a hierarchy ofTestCase-derived classes can beconvenient in sharing fixtures and helper functions, defining testmethods on base classes that are not intended to be instantiateddirectly does not play well with this method. Doing so, however, canbe useful when the fixtures are different and defined in subclasses.

If a module provides aload_tests function it will be called toload the tests. This allows modules to customize test loading.This is theload_tests protocol. Thepattern argument is passed asthe third argument toload_tests.

Changed in version 3.2:Support forload_tests added.

Changed in version 3.5:Support for a keyword-only argumentpattern has been added.

Changed in version 3.12:The undocumented and unofficialuse_load_tests parameter has beenremoved.

loadTestsFromName(name,module=None)

Return a suite of all test cases given a string specifier.

The specifiername is a “dotted name” that may resolve either to amodule, a test case class, a test method within a test case class, aTestSuite instance, or a callable object which returns aTestCase orTestSuite instance. These checks areapplied in the order listed here; that is, a method on a possible testcase class will be picked up as “a test method within a test case class”,rather than “a callable object”.

For example, if you have a moduleSampleTests containing aTestCase-derived classSampleTestCase with three testmethods (test_one(),test_two(), andtest_three()), thespecifier'SampleTests.SampleTestCase' would cause this method toreturn a suite which will run all three test methods. Using the specifier'SampleTests.SampleTestCase.test_two' would cause it to return a testsuite which will run only thetest_two() test method. The specifiercan refer to modules and packages which have not been imported; they willbe imported as a side-effect.

The method optionally resolvesname relative to the givenmodule.

Changed in version 3.5:If anImportError orAttributeError occurs while traversingname then a synthetic test that raises that error when run will bereturned. These errors are included in the errors accumulated byself.errors.

loadTestsFromNames(names,module=None)

Similar toloadTestsFromName(), but takes a sequence of names ratherthan a single name. The return value is a test suite which supports allthe tests defined for each name.

getTestCaseNames(testCaseClass)

Return a sorted sequence of method names found withintestCaseClass;this should be a subclass ofTestCase.

discover(start_dir,pattern='test*.py',top_level_dir=None)

Find all the test modules by recursing into subdirectories from thespecified start directory, and return a TestSuite object containing them.Only test files that matchpattern will be loaded. (Using shell stylepattern matching.) Only module names that are importable (i.e. are validPython identifiers) will be loaded.

All test modules must be importable from the top level of the project. Ifthe start directory is not the top level directory thentop_level_dirmust be specified separately.

If importing a module fails, for example due to a syntax error, thenthis will be recorded as a single error and discovery will continue. Ifthe import failure is due toSkipTest being raised, it will berecorded as a skip instead of an error.

If a package (a directory containing a file named__init__.py) isfound, the package will be checked for aload_tests function. If thisexists then it will be calledpackage.load_tests(loader,tests,pattern). Test discovery takes careto ensure that a package is only checked for tests once during aninvocation, even if the load_tests function itself callsloader.discover.

Ifload_tests exists then discovery doesnot recurse into thepackage,load_tests is responsible for loading all tests in thepackage.

The pattern is deliberately not stored as a loader attribute so thatpackages can continue discovery themselves.

top_level_dir is stored internally, and used as a default to anynested calls todiscover(). That is, if a package’sload_testscallsloader.discover(), it does not need to pass this argument.

start_dir can be a dotted module name as well as a directory.

Added in version 3.2.

Changed in version 3.4:Modules that raiseSkipTest on import are recorded as skips,not errors.

Changed in version 3.4:start_dir can be anamespace packages.

Changed in version 3.4:Paths are sorted before being imported so that execution order is thesame even if the underlying file system’s ordering is not dependenton file name.

Changed in version 3.5:Found packages are now checked forload_tests regardless ofwhether their path matchespattern, because it is impossible fora package name to match the default pattern.

Changed in version 3.11:start_dir can not be anamespace packages.It has been broken since Python 3.7 and Python 3.11 officially remove it.

Changed in version 3.13:top_level_dir is only stored for the duration ofdiscover call.

The following attributes of aTestLoader can be configured either bysubclassing or assignment on an instance:

testMethodPrefix

String giving the prefix of method names which will be interpreted as testmethods. The default value is'test'.

This affectsgetTestCaseNames() and all theloadTestsFrom*methods.

sortTestMethodsUsing

Function to be used to compare method names when sorting them ingetTestCaseNames() and all theloadTestsFrom* methods.

suiteClass

Callable object that constructs a test suite from a list of tests. Nomethods on the resulting object are needed. The default value is theTestSuite class.

This affects all theloadTestsFrom* methods.

testNamePatterns

List of Unix shell-style wildcard test name patterns that test methodshave to match to be included in test suites (see-k option).

If this attribute is notNone (the default), all test methods to beincluded in test suites must match one of the patterns in this list.Note that matches are always performed usingfnmatch.fnmatchcase(),so unlike patterns passed to the-k option, simple substring patternswill have to be converted using* wildcards.

This affects all theloadTestsFrom* methods.

Added in version 3.7.

classunittest.TestResult

This class is used to compile information about which tests have succeededand which have failed.

ATestResult object stores the results of a set of tests. TheTestCase andTestSuite classes ensure that results areproperly recorded; test authors do not need to worry about recording theoutcome of tests.

Testing frameworks built on top ofunittest may want access to theTestResult object generated by running a set of tests for reportingpurposes; aTestResult instance is returned by theTestRunner.run() method for this purpose.

TestResult instances have the following attributes that will be ofinterest when inspecting the results of running a set of tests:

errors

A list containing 2-tuples ofTestCase instances and stringsholding formatted tracebacks. Each tuple represents a test which raised anunexpected exception.

failures

A list containing 2-tuples ofTestCase instances and stringsholding formatted tracebacks. Each tuple represents a test where a failurewas explicitly signalled using theassert* methods.

skipped

A list containing 2-tuples ofTestCase instances and stringsholding the reason for skipping the test.

Added in version 3.1.

expectedFailures

A list containing 2-tuples ofTestCase instances and stringsholding formatted tracebacks. Each tuple represents an expected failureor error of the test case.

unexpectedSuccesses

A list containingTestCase instances that were marked as expectedfailures, but succeeded.

collectedDurations

A list containing 2-tuples of test case names and floatsrepresenting the elapsed time of each test which was run.

Added in version 3.12.

shouldStop

Set toTrue when the execution of tests should stop bystop().

testsRun

The total number of tests run so far.

buffer

If set to true,sys.stdout andsys.stderr will be buffered in betweenstartTest() andstopTest() being called. Collected output willonly be echoed onto the realsys.stdout andsys.stderr if the testfails or errors. Any output is also attached to the failure / error message.

Added in version 3.2.

failfast

If set to truestop() will be called on the first failure or error,halting the test run.

Added in version 3.2.

tb_locals

If set to true then local variables will be shown in tracebacks.

Added in version 3.5.

wasSuccessful()

ReturnTrue if all tests run so far have passed, otherwise returnsFalse.

Changed in version 3.4:ReturnsFalse if there were anyunexpectedSuccessesfrom tests marked with theexpectedFailure() decorator.

stop()

This method can be called to signal that the set of tests being run shouldbe aborted by setting theshouldStop attribute toTrue.TestRunner objects should respect this flag and return withoutrunning any additional tests.

For example, this feature is used by theTextTestRunner class tostop the test framework when the user signals an interrupt from thekeyboard. Interactive tools which provideTestRunnerimplementations can use this in a similar manner.

The following methods of theTestResult class are used to maintainthe internal data structures, and may be extended in subclasses to supportadditional reporting requirements. This is particularly useful in buildingtools which support interactive reporting while tests are being run.

startTest(test)

Called when the test casetest is about to be run.

stopTest(test)

Called after the test casetest has been executed, regardless of theoutcome.

startTestRun()

Called once before any tests are executed.

Added in version 3.1.

stopTestRun()

Called once after all tests are executed.

Added in version 3.1.

addError(test,err)

Called when the test casetest raises an unexpected exception.err is atuple of the form returned bysys.exc_info():(type,value,traceback).

The default implementation appends a tuple(test,formatted_err) tothe instance’serrors attribute, whereformatted_err is aformatted traceback derived fromerr.

addFailure(test,err)

Called when the test casetest signals a failure.err is a tuple ofthe form returned bysys.exc_info():(type,value,traceback).

The default implementation appends a tuple(test,formatted_err) tothe instance’sfailures attribute, whereformatted_err is aformatted traceback derived fromerr.

addSuccess(test)

Called when the test casetest succeeds.

The default implementation does nothing.

addSkip(test,reason)

Called when the test casetest is skipped.reason is the reason thetest gave for skipping.

The default implementation appends a tuple(test,reason) to theinstance’sskipped attribute.

addExpectedFailure(test,err)

Called when the test casetest fails or errors, but was marked withtheexpectedFailure() decorator.

The default implementation appends a tuple(test,formatted_err) tothe instance’sexpectedFailures attribute, whereformatted_erris a formatted traceback derived fromerr.

addUnexpectedSuccess(test)

Called when the test casetest was marked with theexpectedFailure() decorator, but succeeded.

The default implementation appends the test to the instance’sunexpectedSuccesses attribute.

addSubTest(test,subtest,outcome)

Called when a subtest finishes.test is the test casecorresponding to the test method.subtest is a customTestCase instance describing the subtest.

Ifoutcome isNone, the subtest succeeded. Otherwise,it failed with an exception whereoutcome is a tuple of the formreturned bysys.exc_info():(type,value,traceback).

The default implementation does nothing when the outcome is asuccess, and records subtest failures as normal failures.

Added in version 3.4.

addDuration(test,elapsed)

Called when the test case finishes.elapsed is the time represented inseconds, and it includes the execution of cleanup functions.

Added in version 3.12.

classunittest.TextTestResult(stream,descriptions,verbosity,*,durations=None)

A concrete implementation ofTestResult used by theTextTestRunner. Subclasses should accept**kwargs to ensurecompatibility as the interface changes.

Added in version 3.2.

Changed in version 3.12:Added thedurations keyword parameter.

unittest.defaultTestLoader

Instance of theTestLoader class intended to be shared. If nocustomization of theTestLoader is needed, this instance can be usedinstead of repeatedly creating new instances.

classunittest.TextTestRunner(stream=None,descriptions=True,verbosity=1,failfast=False,buffer=False,resultclass=None,warnings=None,*,tb_locals=False,durations=None)

A basic test runner implementation that outputs results to a stream. IfstreamisNone, the default,sys.stderr is used as the output stream. This classhas a few configurable parameters, but is essentially very simple. Graphicalapplications which run test suites should provide alternate implementations. Suchimplementations should accept**kwargs as the interface to construct runnerschanges when features are added to unittest.

By default this runner showsDeprecationWarning,PendingDeprecationWarning,ResourceWarning andImportWarning even if they areignored by default. This behavior canbe overridden using Python’s-Wd or-Wa options(seeWarning control) and leavingwarnings toNone.

Changed in version 3.2:Added thewarnings parameter.

Changed in version 3.2:The default stream is set tosys.stderr at instantiation time ratherthan import time.

Changed in version 3.5:Added thetb_locals parameter.

Changed in version 3.12:Added thedurations parameter.

_makeResult()

This method returns the instance ofTestResult used byrun().It is not intended to be called directly, but can be overridden insubclasses to provide a customTestResult.

_makeResult() instantiates the class or callable passed in theTextTestRunner constructor as theresultclass argument. Itdefaults toTextTestResult if noresultclass is provided.The result class is instantiated with the following arguments:

stream,descriptions,verbosity
run(test)

This method is the main public interface to theTextTestRunner. Thismethod takes aTestSuite orTestCase instance. ATestResult is created by calling_makeResult() and the test(s) are run and theresults printed to stdout.

unittest.main(module='__main__',defaultTest=None,argv=None,testRunner=None,testLoader=unittest.defaultTestLoader,exit=True,verbosity=1,failfast=None,catchbreak=None,buffer=None,warnings=None)

A command-line program that loads a set of tests frommodule and runs them;this is primarily for making test modules conveniently executable.The simplest use for this function is to include the following line at theend of a test script:

if__name__=='__main__':unittest.main()

You can run tests with more detailed information by passing in the verbosityargument:

if__name__=='__main__':unittest.main(verbosity=2)

ThedefaultTest argument is either the name of a single test or aniterable of test names to run if no test names are specified viaargv. Ifnot specified orNone and no test names are provided viaargv, alltests found inmodule are run.

Theargv argument can be a list of options passed to the program, with thefirst element being the program name. If not specified orNone,the values ofsys.argv are used.

ThetestRunner argument can either be a test runner class or an alreadycreated instance of it. By defaultmain callssys.exit() withan exit code indicating success (0) or failure (1) of the tests run.An exit code of 5 indicates that no tests were run or skipped.

ThetestLoader argument has to be aTestLoader instance,and defaults todefaultTestLoader.

main supports being used from the interactive interpreter by passing in theargumentexit=False. This displays the result on standard output withoutcallingsys.exit():

>>>fromunittestimportmain>>>main(module='test_module',exit=False)

Thefailfast,catchbreak andbuffer parameters have the sameeffect as the same-namecommand-line options.

Thewarnings argument specifies thewarning filterthat should be used while running the tests. If it’s not specified, it willremainNone if a-W option is passed topython(seeWarning control),otherwise it will be set to'default'.

Callingmain returns an object with theresult attribute that containsthe result of the tests run as aunittest.TestResult.

Changed in version 3.1:Theexit parameter was added.

Changed in version 3.2:Theverbosity,failfast,catchbreak,bufferandwarnings parameters were added.

Changed in version 3.4:ThedefaultTest parameter was changed to also accept an iterable oftest names.

load_tests Protocol

Added in version 3.2.

Modules or packages can customize how tests are loaded from them during normaltest runs or test discovery by implementing a function calledload_tests.

If a test module definesload_tests it will be called byTestLoader.loadTestsFromModule() with the following arguments:

load_tests(loader,standard_tests,pattern)

wherepattern is passed straight through fromloadTestsFromModule. Itdefaults toNone.

It should return aTestSuite.

loader is the instance ofTestLoader doing the loading.standard_tests are the tests that would be loaded by default from themodule. It is common for test modules to only want to add or remove testsfrom the standard set of tests.The third argument is used when loading packages as part of test discovery.

A typicalload_tests function that loads tests from a specific set ofTestCase classes may look like:

test_cases=(TestCase1,TestCase2,TestCase3)defload_tests(loader,tests,pattern):suite=TestSuite()fortest_classintest_cases:tests=loader.loadTestsFromTestCase(test_class)suite.addTests(tests)returnsuite

If discovery is started in a directory containing a package, either from thecommand line or by callingTestLoader.discover(), then the package__init__.py will be checked forload_tests. If that function doesnot exist, discovery will recurse into the package as though it were justanother directory. Otherwise, discovery of the package’s tests will be left uptoload_tests which is called with the following arguments:

load_tests(loader,standard_tests,pattern)

This should return aTestSuite representing all the testsfrom the package. (standard_tests will only contain testscollected from__init__.py.)

Because the pattern is passed intoload_tests the package is free tocontinue (and potentially modify) test discovery. A ‘do nothing’load_tests function for a test package would look like:

defload_tests(loader,standard_tests,pattern):# top level directory cached on loader instancethis_dir=os.path.dirname(__file__)package_tests=loader.discover(start_dir=this_dir,pattern=pattern)standard_tests.addTests(package_tests)returnstandard_tests

Changed in version 3.5:Discovery no longer checks package names for matchingpattern due to theimpossibility of package names matching the default pattern.

Class and Module Fixtures

Class and module level fixtures are implemented inTestSuite. Whenthe test suite encounters a test from a new class thentearDownClass()from the previous class (if there is one) is called, followed bysetUpClass() from the new class.

Similarly if a test is from a different module from the previous test thentearDownModule from the previous module is run, followed bysetUpModule from the new module.

After all the tests have run the finaltearDownClass andtearDownModule are run.

Note that shared fixtures do not play well with [potential] features like testparallelization and they break test isolation. They should be used with care.

The default ordering of tests created by the unittest test loaders is to groupall tests from the same modules and classes together. This will lead tosetUpClass /setUpModule (etc) being called exactly once per class andmodule. If you randomize the order, so that tests from different modules andclasses are adjacent to each other, then these shared fixture functions may becalled multiple times in a single test run.

Shared fixtures are not intended to work with suites with non-standardordering. ABaseTestSuite still exists for frameworks that don’t want tosupport shared fixtures.

If there are any exceptions raised during one of the shared fixture functionsthe test is reported as an error. Because there is no corresponding testinstance an_ErrorHolder object (that has the same interface as aTestCase) is created to represent the error. If you are just usingthe standard unittest test runner then this detail doesn’t matter, but if youare a framework author it may be relevant.

setUpClass and tearDownClass

These must be implemented as class methods:

importunittestclassTest(unittest.TestCase):@classmethoddefsetUpClass(cls):cls._connection=createExpensiveConnectionObject()@classmethoddeftearDownClass(cls):cls._connection.destroy()

If you want thesetUpClass andtearDownClass on base classes calledthen you must call up to them yourself. The implementations inTestCase are empty.

If an exception is raised during asetUpClass then the tests in the classare not run and thetearDownClass is not run. Skipped classes will nothavesetUpClass ortearDownClass run. If the exception is aSkipTest exception then the class will be reported as having been skippedinstead of as an error.

setUpModule and tearDownModule

These should be implemented as functions:

defsetUpModule():createConnection()deftearDownModule():closeConnection()

If an exception is raised in asetUpModule then none of the tests in themodule will be run and thetearDownModule will not be run. If the exception is aSkipTest exception then the module will be reported as having been skippedinstead of as an error.

To add cleanup code that must be run even in the case of an exception, useaddModuleCleanup:

unittest.addModuleCleanup(function,/,*args,**kwargs)

Add a function to be called aftertearDownModule() to cleanupresources used during the test class. Functions will be called in reverseorder to the order they are added (LIFO).They are called with any arguments and keyword arguments passed intoaddModuleCleanup() when they are added.

IfsetUpModule() fails, meaning thattearDownModule() is notcalled, then any cleanup functions added will still be called.

Added in version 3.8.

classmethodunittest.enterModuleContext(cm)

Enter the suppliedcontext manager. If successful, alsoadd its__exit__() method as a cleanup function byaddModuleCleanup() and return the result of the__enter__() method.

Added in version 3.11.

unittest.doModuleCleanups()

This function is called unconditionally aftertearDownModule(), oraftersetUpModule() ifsetUpModule() raises an exception.

It is responsible for calling all the cleanup functions added byaddModuleCleanup(). If you need cleanup functions to be calledprior totearDownModule() then you can calldoModuleCleanups() yourself.

doModuleCleanups() pops methods off the stack of cleanupfunctions one at a time, so it can be called at any time.

Added in version 3.8.

Signal Handling

Added in version 3.2.

The-c/--catch command-line option to unittest,along with thecatchbreak parameter tounittest.main(), providemore friendly handling of control-C during a test run. With catch breakbehavior enabled control-C will allow the currently running test to complete,and the test run will then end and report all the results so far. A secondcontrol-c will raise aKeyboardInterrupt in the usual way.

The control-c handling signal handler attempts to remain compatible with code ortests that install their ownsignal.SIGINT handler. If theunittesthandler is called butisn’t the installedsignal.SIGINT handler,i.e. it has been replaced by the system under test and delegated to, then itcalls the default handler. This will normally be the expected behavior by codethat replaces an installed handler and delegates to it. For individual teststhat needunittest control-c handling disabled theremoveHandler()decorator can be used.

There are a few utility functions for framework authors to enable control-chandling functionality within test frameworks.

unittest.installHandler()

Install the control-c handler. When asignal.SIGINT is received(usually in response to the user pressing control-c) all registered resultshavestop() called.

unittest.registerResult(result)

Register aTestResult object for control-c handling. Registering aresult stores a weak reference to it, so it doesn’t prevent the result frombeing garbage collected.

Registering aTestResult object has no side-effects if control-chandling is not enabled, so test frameworks can unconditionally registerall results they create independently of whether or not handling is enabled.

unittest.removeResult(result)

Remove a registered result. Once a result has been removed thenstop() will no longer be called on that result object inresponse to a control-c.

unittest.removeHandler(function=None)

When called without arguments this function removes the control-c handlerif it has been installed. This function can also be used as a test decoratorto temporarily remove the handler while the test is being executed:

@unittest.removeHandlerdeftest_signal_handling(self):...