Configure a mock object's method to return a fixed value when invoked.

Indicates the intended behavior of a mocked method in a test, specifying what the method should return.

When writing unit tests that need to isolate the unit under test from its dependencies by replacing those dependencies with mocks and defining their return values.

Unit test files using the unittest.mock library, typically within test methods or setup functions, when stubbing dependencies.

mock_method.return_value = <value>

object.attribute = literal_or_expression where object is a mock, attribute is a method name, and the assigned value is the return value.

mock_method: a Mock object's method attribute (e.g., some_mock.method); return_value: any Python object or expression to be returned when the method is called.

• unittest.mock.Mock
• unittest.mock.patch
• assert_called_with
• assert_called_once_with
• side_effect

• Using side_effect to return a value or raise an exception (e.g.
• mock_method.side_effect = lambda: 42)
• using PropertyMock for properties
• using a lambda for dynamic return values.

Forgetting to call the method after setting return_value, leading to untested code (cause: misunderstanding that setting return_value invokes the method; consequence: test passes incorrectly). Assigning return_value to a property instead of a method, causing AttributeError when the property is accessed as a method (cause: confusion between attributes and methods; consequence: test fails with AttributeError). Setting return_value after the mock has already been used, so earlier calls receive default behavior (cause: ordering mistake; consequence: intermittent test failures). Using return_value on a spec‑restricted mock for a non‑existent method, causing AttributeError (cause: spec mismatch; consequence: test setup fails). Confusing return_value with side_effect, leading to unexpected exceptions or None returns (cause: misunderstanding mock attributes; consequence: test behaves unexpectedly).

mock_method.side_effect: used to dynamically compute return values or raise exceptions, unlike the fixed return_value. PropertyMock: used to mock properties rather than methods. Real method call: using the actual dependency instead of a mock, which tests integration rather than isolation. Stub vs. mock: stubs provide canned responses (like return_value) but lack behavior verification; mocks allow asserting that calls were made.

Coming from Java: may use Mockito's when(...).thenReturn(...) syntax and expect a chained call; in Python's unittest.mock, return_value is set via attribute assignment, not a chained method → use mock_method.return_value = value. Coming from JavaScript Jest: may expect jest.fn().mockReturnValue(value); the Python equivalent is mock.return_value = value → assign directly. Coming from C# Moq: may use mock.Setup(m => m.Method()).Returns(value); Python's mock uses attribute assignment → use mock_method.return_value = value. Coming from Ruby RSpec: may expect allow(object).to receive(:method).and_return(value); Python uses mock_method.return_value = value → direct assignment.

• mocking idioms
• mock configuration patterns

Do not use when the method's return value should depend on input arguments or state; a fixed return_value can hide bugs where the method's logic varies with input. Performance impact is negligible as attribute assignment is O(1) and occurs only during test setup. Boundary note: if the method is accessed as a property (e.g., via @property), setting return_value on the underlying function will not work; you must use PropertyMock instead.

Ensures that dependent code receives predictable, controllable responses from dependencies, enabling reliable unit tests that isolate the unit under test and produce fast, deterministic outcomes.

Setting a mock's return value is like programming a vending machine to always dispense a specific snack when the button is pressed, regardless of what the user actually selects.

When using spec=True or autospec=True, the mock will only allow attributes that exist on the spec; attempting to set return_value on a non‑existent attribute raises AttributeError.