Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Python

unittest results: tests run, failures, and errors

Run a test suite and use the returned result to count test cases started, assertion failures, and unexpected exceptions separately.

Version: Python 3.12

Syntax

result = unittest.TextTestRunner(stream=stream).run(suite)
result.testsRun
len(result.failures)
len(result.errors)

In Python 3.12, unittest.TextTestRunner.run(suite) executes the suite and returns a TestResult object. result.testsRun counts test cases started, not cases found during discovery or only those that passed. A case skipped after it starts can still count.

result.failures records failures such as a failed assertEqual() check. TestCase assertions signal failure with failureException, which defaults to AssertionError. result.errors records unexpected exceptions, such as an unhandled RuntimeError in a test method. Each entry in either list is a pair: the test object and a string containing a formatted traceback.

Use len(result.failures) and len(result.errors) to count entries without parsing the text report. Don't subtract those counts from testsRun to calculate passes: tests can be skipped, and a single case can have several failing subtests. For the overall outcome, use result.wasSuccessful(), which also returns False for an unexpected success.

Examples

import unittest
from io import StringIO


class SummaryTests(unittest.TestCase):
    def test_pass(self):
        self.assertEqual(1 + 1, 2)

    def test_failure(self):
        self.assertEqual(1 + 1, 3)

    def test_error(self):
        raise RuntimeError("unexpected problem")


suite = unittest.TestSuite([
    SummaryTests("test_pass"),
    SummaryTests("test_failure"),
    SummaryTests("test_error"),
])
result = unittest.TextTestRunner(stream=StringIO()).run(suite)
print(f"testsRun={result.testsRun} failures={len(result.failures)} errors={len(result.errors)}")

Result

testsRun=3 failures=1 errors=1

One case passes, one fails an assertion, and one raises `RuntimeError`. `StringIO` captures the runner's report, so the console shows only the count line.

Related lessons

  • Python · Lesson 37 · Advanced · Version: 5

Sources