Why does a unittest pass alone but fail with the whole test suite?

First capture the exact failure: the assertion or exception and the test name. Then ask whether the test reads or changes anything that can outlive it, such as a module-level list or dictionary, a class attribute, a file, or an environment setting. These are things to inspect, not proof of the cause.

Run the failing test by itself, then run the suite and note whether the same test fails. Look for an earlier test that changes the same state. Each TestCase should be self-contained and runnable alone or with other cases. unittest orders test methods by name, so a test that silently relies on another test running first is fragile. [S1]

Suppose a module contains a shared list and two tests append to it. The second test may expect an empty list when run alone, but encounter the first test’s value in the suite. Here is a small illustrative example:

import unittest

items = []

class ItemTests(unittest.TestCase):
    def test_add_one(self):
        items.append("one")
        self.assertEqual(items, ["one"])

    def test_add_two(self):
        items.append("two")
        self.assertEqual(items, ["two"])

Both tests assume the list starts empty, but neither establishes that condition. This example illustrates the risk; it is not a recommendation to use global state in tests.

Create fresh test data in setUp(), which unittest runs for each test. [S1] Replace the shared list with an instance attribute:

import unittest

class ItemTests(unittest.TestCase):
    def setUp(self):
        self.items = []

    def test_add_one(self):
        self.items.append("one")
        self.assertEqual(self.items, ["one"])

    def test_add_two(self):
        self.items.append("two")
        self.assertEqual(self.items, ["two"])

Each method now starts with its own empty list. For state that cannot simply be recreated, identify what the test changes and restore it in cleanup. unittest documents that tearDown() runs even if the test method fails, provided setUp() succeeded. [S1] Avoid relying on a later test to perform cleanup.

Compare the conditions around the failure rather than changing several tests at once. Check whether the test uses a shared fixture or class or module attribute, whether it assumes a particular prior test, and whether it cleans up after modifying state. If useful, temporarily run the failing test with a suspected predecessor, then without it, to check that hypothesis. Keep the smallest reproducing case and make its starting state explicit.

A practical investigation note could look like this:

Failing test: test_add_two
State it reads: module-level items list
State it changes: appends "two"
Expected starting state: empty list
Possible source: another test appended without resetting
Isolation change to try: create a fresh list in setUp()

This narrows the investigation; it does not establish that every suite-only failure comes from shared state. The documentation supports checking independence, ordering, and cleanup, but does not identify the cause of a particular failure. [S1]