命令列模式選項¶

unittest 支援以下命令列選項：

-b,--buffer¶

Standard output 與 standard error stream 將在測試執行被緩衝 (buffer)。這些輸出在測試通過時被丟棄。若是測試錯誤或失則，這些輸出將會正常地被印出，並且被加入至錯誤訊息中。

-c,--catch¶

Control-C 測試執行過程中等待正確的測試結果並回報目前為止所有的測試結果。第二個Control-C 拋出一般例外KeyboardInterrupt。

參照Signal Handling 針對函式提供的功能。

-f,--failfast¶

在第一次錯誤或是失敗停止執行測試。

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

透過 traceback 顯示本地變數。

--durationsN¶

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

對執行所有的專案或是一個子集合測試，命令列模式可以可以被用來做測試探索。

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.

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

更多細節請見Class and Module Fixtures。

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

更多細節請見Class and Module Fixtures。

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

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

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

更多資訊請見Distinguishing test iterations using subtests。

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

方法	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).

在 3.1 版的變更:Added the automatic calling of type-specific equality function.

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

在 3.1 版被加入.

assertIsNone(expr,msg=None)¶

assertIsNotNone(expr,msg=None)¶

Test thatexpr is (or is not)None.

在 3.1 版被加入.

assertIn(member,container,msg=None)¶

assertNotIn(member,container,msg=None)¶

Test thatmember is (or is not) incontainer.

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

在 3.2 版被加入.

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

方法	Checks that	New in
assertRaises(exc,fun,*args,**kwds)	fun(*args,**kwds) 會引發exc
assertRaisesRegex(exc,r,fun,*args,**kwds)	fun(*args,**kwds) raisesexcand the message matches regexr	3.1
assertWarns(warn,fun,*args,**kwds)	fun(*args,**kwds) 會引發warn	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)

在 3.1 版的變更:新增assertRaises() 可作為情境管理器使用的能力。

在 3.2 版的變更:新增exception 屬性。

在 3.3 版的變更:新增作為情境管理器使用時的msg 引數。

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

或是：

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

在 3.1 版被加入:以assertRaisesRegexp 為名新增。

在 3.2 版的變更:重新命名為assertRaisesRegex()。

在 3.3 版的變更:新增作為情境管理器使用時的msg 引數。

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.

在 3.2 版被加入.

在 3.3 版的變更:新增作為情境管理器使用時的msg 引數。

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

或是：

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

在 3.2 版被加入.

在 3.3 版的變更:新增作為情境管理器使用時的msg 引數。

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.

範例：

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'])

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

在 3.10 版被加入.

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

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

在 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"

在 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().

在 3.1 版被加入:以assertRegexpMatches 為名新增。

在 3.2 版的變更:assertRegexpMatches() 方法已重新命名為assertRegex()。

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

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

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

方法	Used to compare	New in
assertMultiLineEqual(a,b)	字串	3.1
assertSequenceEqual(a,b)	序列	3.1
assertListEqual(a,b)	串列	3.1
assertTupleEqual(a,b)	元組	3.1
assertSetEqual(a,b)	集合或凍結集合	3.1
assertDictEqual(a,b)	字典	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().

在 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().

在 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().

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

在 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().

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

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

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

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

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

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

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

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

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

在 3.8 版被加入.

classunittest.IsolatedAsyncioTestCase(methodName='runTest')¶

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

在 3.8 版被加入.

loop_factory¶

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

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

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

在 3.2 版的變更:In earlier versions theTestSuite accessed tests directly ratherthan through iteration, so overriding__iter__() wasn't sufficientfor providing tests.

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

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

備註

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.

在 3.2 版的變更:Support forload_tests added.

在 3.5 版的變更:Support for a keyword-only argumentpattern has been added.

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

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

在 3.2 版被加入.

在 3.4 版的變更:Modules that raiseSkipTest on import are recorded as skips,not errors.

在 3.4 版的變更:start_dir can be anamespace packages.

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

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

在 3.11 版的變更:start_dir can not be anamespace packages.It has been broken since Python 3.7 and Python 3.11 officially remove it.

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

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

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

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

在 3.2 版被加入.

failfast¶

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

在 3.2 版被加入.

tb_locals¶

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

在 3.5 版被加入.

wasSuccessful()¶

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

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

在 3.1 版被加入.

stopTestRun()¶

Called once after all tests are executed.

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

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

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

在 3.2 版被加入.

在 3.12 版的變更:新增durations 關鍵字參數。

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.

在 3.2 版的變更:新增warnings 參數。

在 3.2 版的變更:The default stream is set tosys.stderr at instantiation time ratherthan import time.

在 3.5 版的變更:新增tb_locals 參數。

在 3.12 版的變更:新增durations 參數。

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

在 3.1 版的變更:新增exit 參數。

在 3.2 版的變更:Theverbosity,failfast,catchbreak,bufferandwarnings parameters were added.

在 3.4 版的變更:ThedefaultTest parameter was changed to also accept an iterable oftest names.

load_tests(loader,standard_tests,pattern)

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

load_tests(loader,standard_tests,pattern)

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

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

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

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

在 3.8 版被加入.